<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Chapter 17 Replication</title>
<link rel="stylesheet" href="mvl.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets + chunker.py v1.9.2" />
<link rel="start" href="index.html" title="{book-title}" />
<link rel="up" href="" title="" />
<link rel="prev" href="storage-engines.html" title="Chapter 16 Alternative Storage Engines" />
<link rel="next" href="group-replication.html" title="Chapter 18 Group Replication" />
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 17 Replication</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="storage-engines.html">Prev</a> </td>
<th width="60%" align="center"></th>
<td width="20%" align="right"> <a accesskey="n" href="group-replication.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a name="replication"></a>Chapter 17 Replication</h1>

</div>

</div>

</div>
<div class="toc">
<p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="replication.html#replication-configuration">17.1 Configuring Replication</a></span></dt><dd><dl><dt><span class="section"><a href="replication.html#binlog-replication-configuration-overview">17.1.1 Binary Log File Position Based Replication Configuration Overview</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto">17.1.2 Setting Up Binary Log File Position Based Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids">17.1.3 Replication with Global Transaction Identifiers</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source">17.1.4 MySQL Multi-Source Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-mode-change-online">17.1.5 Changing Replication Modes on Online Servers</a></span></dt><dt><span class="section"><a href="replication.html#replication-options">17.1.6 Replication and Binary Logging Options and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-administration">17.1.7 Common Replication Administration Tasks</a></span></dt></dl></dd><dt><span class="section"><a href="replication.html#replication-implementation">17.2 Replication Implementation</a></span></dt><dd><dl><dt><span class="section"><a href="replication.html#replication-formats">17.2.1 Replication Formats</a></span></dt><dt><span class="section"><a href="replication.html#replication-implementation-details">17.2.2 Replication Implementation Details</a></span></dt><dt><span class="section"><a href="replication.html#replication-channels">17.2.3 Replication Channels</a></span></dt><dt><span class="section"><a href="replication.html#slave-logs">17.2.4 Replication Relay and Status Logs</a></span></dt><dt><span class="section"><a href="replication.html#replication-rules">17.2.5 How Servers Evaluate Replication Filtering Rules</a></span></dt></dl></dd><dt><span class="section"><a href="replication.html#replication-security">17.3 Replication Security</a></span></dt><dd><dl><dt><span class="section"><a href="replication.html#replication-solutions-encrypted-connections">17.3.1 Setting Up Replication to Use Encrypted Connections</a></span></dt><dt><span class="section"><a href="replication.html#replication-binlog-encryption">17.3.2 Encrypting Binary Log Files and Relay Log Files</a></span></dt><dt><span class="section"><a href="replication.html#replication-privilege-checks">17.3.3 Replication Privilege Checks</a></span></dt></dl></dd><dt><span class="section"><a href="replication.html#replication-solutions">17.4 Replication Solutions</a></span></dt><dd><dl><dt><span class="section"><a href="replication.html#replication-solutions-backups">17.4.1 Using Replication for Backups</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-unexpected-slave-halt">17.4.2 Handling an Unexpected Halt of a Replication Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-rbr-monitoring">17.4.3 Monitoring Row-based Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-diffengines">17.4.4 Using Replication with Different Master and Slave Storage Engines</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-scaleout">17.4.5 Using Replication for Scale-Out</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-partitioning">17.4.6 Replicating Different Databases to Different Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-performance">17.4.7 Improving Replication Performance</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-switch">17.4.8 Switching Masters During Failover</a></span></dt><dt><span class="section"><a href="replication.html#replication-semisync">17.4.9 Semisynchronous Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-delayed">17.4.10 Delayed Replication</a></span></dt></dl></dd><dt><span class="section"><a href="replication.html#replication-notes">17.5 Replication Notes and Tips</a></span></dt><dd><dl><dt><span class="section"><a href="replication.html#replication-features">17.5.1 Replication Features and Issues</a></span></dt><dt><span class="section"><a href="replication.html#replication-compatibility">17.5.2 Replication Compatibility Between MySQL Versions</a></span></dt><dt><span class="section"><a href="replication.html#replication-upgrade">17.5.3 Upgrading a Replication Setup</a></span></dt><dt><span class="section"><a href="replication.html#replication-problems">17.5.4 Troubleshooting Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-bugs">17.5.5 How to Report Replication Bugs or Problems</a></span></dt></dl></dd></dl>
</div>
<a class="indexterm" name="idm46444272150448"></a><a class="indexterm" name="idm46444272149376"></a><a class="indexterm" name="idm46444272147888"></a><a class="indexterm" name="idm46444272146384"></a><p>
    Replication enables data from one MySQL database server (the master)
    to be copied to one or more MySQL database servers (the slaves).
    Replication is asynchronous by default; slaves do not need to be
    connected permanently to receive updates from the master. Depending
    on the configuration, you can replicate all databases, selected
    databases, or even selected tables within a database.
  </p><p>
    Advantages of replication in MySQL include:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Scale-out solutions - spreading the load among multiple slaves
        to improve performance. In this environment, all writes and
        updates must take place on the master server. Reads, however,
        may take place on one or more slaves. This model can improve the
        performance of writes (since the master is dedicated to
        updates), while dramatically increasing read speed across an
        increasing number of slaves.
      </p></li><li class="listitem"><p>
        Data security - because data is replicated to the slave, and the
        slave can pause the replication process, it is possible to run
        backup services on the slave without corrupting the
        corresponding master data.
      </p></li><li class="listitem"><p>
        Analytics - live data can be created on the master, while the
        analysis of the information can take place on the slave without
        affecting the performance of the master.
      </p></li><li class="listitem"><p>
        Long-distance data distribution - you can use replication to
        create a local copy of data for a remote site to use, without
        permanent access to the master.
</p></li></ul>
</div>
<p>
    For information on how to use replication in such scenarios, see
    <a class="xref" href="replication.html#replication-solutions" title="17.4 Replication Solutions">Section 17.4, “Replication Solutions”</a>.
  </p><p>
    MySQL 8.0 supports different methods of replication.
    The traditional method is based on replicating events from the
    master's binary log, and requires the log files and positions in
    them to be synchronized between master and slave. The newer method
    based on <span class="firstterm">global transaction
    identifiers</span> (GTIDs) is transactional and therefore does
    not require working with log files or positions within these files,
    which greatly simplifies many common replication tasks. Replication
    using GTIDs guarantees consistency between master and slave as long
    as all transactions committed on the master have also been applied
    on the slave. For more information about GTIDs and GTID-based
    replication in MySQL, see <a class="xref" href="replication.html#replication-gtids" title="17.1.3 Replication with Global Transaction Identifiers">Section 17.1.3, “Replication with Global Transaction Identifiers”</a>. For
    information on using binary log file position based replication, see
    <a class="xref" href="replication.html#replication-configuration" title="17.1 Configuring Replication">Section 17.1, “Configuring Replication”</a>.
  </p><p>
    Replication in MySQL supports different types of synchronization.
    The original type of synchronization is one-way, asynchronous
    replication, in which one server acts as the master, while one or
    more other servers act as slaves. This is in contrast to the
    <span class="emphasis"><em>synchronous</em></span> replication which is a
    characteristic of NDB Cluster (see <a class="xref" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0">Chapter 22, <i>MySQL NDB Cluster 8.0</i></a>).
    In MySQL 8.0, semisynchronous replication is supported
    in addition to the built-in asynchronous replication. With
    semisynchronous replication, a commit performed on the master blocks
    before returning to the session that performed the transaction until
    at least one slave acknowledges that it has received and logged the
    events for the transaction; see
    <a class="xref" href="replication.html#replication-semisync" title="17.4.9 Semisynchronous Replication">Section 17.4.9, “Semisynchronous Replication”</a>. MySQL 8.0 also
    supports delayed replication such that a slave server deliberately
    lags behind the master by at least a specified amount of time; see
    <a class="xref" href="replication.html#replication-delayed" title="17.4.10 Delayed Replication">Section 17.4.10, “Delayed Replication”</a>. For scenarios where
    <span class="emphasis"><em>synchronous</em></span> replication is required, use NDB
    Cluster (see <a class="xref" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0">Chapter 22, <i>MySQL NDB Cluster 8.0</i></a>).
  </p><p>
    There are a number of solutions available for setting up replication
    between servers, and the best method to use depends on the presence
    of data and the engine types you are using. For more information on
    the available options, see <a class="xref" href="replication.html#replication-howto" title="17.1.2 Setting Up Binary Log File Position Based Replication">Section 17.1.2, “Setting Up Binary Log File Position Based Replication”</a>.
  </p><p>
    There are two core types of replication format, Statement Based
    Replication (SBR), which replicates entire SQL statements, and Row
    Based Replication (RBR), which replicates only the changed rows. You
    can also use a third variety, Mixed Based Replication (MBR). For
    more information on the different replication formats, see
    <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
  </p><p>
    Replication is controlled through a number of different options and
    variables. For more information, see
    <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>. Additional security measures
    can be applied to a replication topology, as described in
    <a class="xref" href="replication.html#replication-security" title="17.3 Replication Security">Section 17.3, “Replication Security”</a>.
  </p><p>
    You can use replication to solve a number of different problems,
    including performance, supporting the backup of different databases,
    and as part of a larger solution to alleviate system failures. For
    information on how to address these issues, see
    <a class="xref" href="replication.html#replication-solutions" title="17.4 Replication Solutions">Section 17.4, “Replication Solutions”</a>.
  </p><p>
    For notes and tips on how different data types and statements are
    treated during replication, including details of replication
    features, version compatibility, upgrades, and potential problems
    and their resolution, see <a class="xref" href="replication.html#replication-notes" title="17.5 Replication Notes and Tips">Section 17.5, “Replication Notes and Tips”</a>. For
    answers to some questions often asked by those who are new to MySQL
    Replication, see <a class="xref" href="faqs.html#faqs-replication" title="A.14 MySQL 8.0 FAQ: Replication">Section A.14, “MySQL 8.0 FAQ: Replication”</a>.
  </p><p>
    For detailed information on the implementation of replication, how
    replication works, the process and contents of the binary log,
    background threads and the rules used to decide how statements are
    recorded and replicated, see
    <a class="xref" href="replication.html#replication-implementation" title="17.2 Replication Implementation">Section 17.2, “Replication Implementation”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="replication-configuration"></a>17.1 Configuring Replication</h2>

</div>

</div>

</div>

<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#binlog-replication-configuration-overview">17.1.1 Binary Log File Position Based Replication Configuration Overview</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto">17.1.2 Setting Up Binary Log File Position Based Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids">17.1.3 Replication with Global Transaction Identifiers</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source">17.1.4 MySQL Multi-Source Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-mode-change-online">17.1.5 Changing Replication Modes on Online Servers</a></span></dt><dt><span class="section"><a href="replication.html#replication-options">17.1.6 Replication and Binary Logging Options and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-administration">17.1.7 Common Replication Administration Tasks</a></span></dt></dl>
</div>
<p>
    This section describes how to configure the different types of
    replication available in MySQL and includes the setup and
    configuration required for a replication environment, including
    step-by-step instructions for creating a new replication
    environment. The major components of this section are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        For a guide to setting up two or more servers for replication
        using binary log file positions,
        <a class="xref" href="replication.html#replication-howto" title="17.1.2 Setting Up Binary Log File Position Based Replication">Section 17.1.2, “Setting Up Binary Log File Position Based Replication”</a>, deals with the
        configuration of the servers and provides methods for copying
        data between the master and slaves.
      </p></li><li class="listitem"><p>
        For a guide to setting up two or more servers for replication
        using GTID transactions, <a class="xref" href="replication.html#replication-gtids" title="17.1.3 Replication with Global Transaction Identifiers">Section 17.1.3, “Replication with Global Transaction Identifiers”</a>,
        deals with the configuration of the servers.
      </p></li><li class="listitem"><p>
        Events in the binary log are recorded using a number of formats.
        These are referred to as statement-based replication (SBR) or
        row-based replication (RBR). A third type, mixed-format
        replication (MIXED), uses SBR or RBR replication automatically
        to take advantage of the benefits of both SBR and RBR formats
        when appropriate. The different formats are discussed in
        <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
      </p></li><li class="listitem"><p>
        Detailed information on the different configuration options and
        variables that apply to replication is provided in
        <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
      </p></li><li class="listitem"><p>
        Once started, the replication process should require little
        administration or monitoring. However, for advice on common
        tasks that you may want to execute, see
        <a class="xref" href="replication.html#replication-administration" title="17.1.7 Common Replication Administration Tasks">Section 17.1.7, “Common Replication Administration Tasks”</a>.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="binlog-replication-configuration-overview"></a>17.1.1 Binary Log File Position Based Replication Configuration Overview</h3>

</div>

</div>

</div>
<p>
      This section describes replication between MySQL servers based on
      the binary log file position method, where the MySQL instance
      operating as the master (the source of the database changes)
      writes updates and changes as <span class="quote">“<span class="quote">events</span>”</span> to the binary
      log. The information in the binary log is stored in different
      logging formats according to the database changes being recorded.
      Slaves are configured to read the binary log from the master and
      to execute the events in the binary log on the slave's local
      database.
    </p><p>
      Each slave receives a copy of the entire contents of the binary
      log. It is the responsibility of the slave to decide which
      statements in the binary log should be executed. Unless you
      specify otherwise, all events in the master binary log are
      executed on the slave. If required, you can configure the slave to
      process only events that apply to particular databases or tables.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        You cannot configure the master to log only certain events.
</p>
</div>
<p>
      Each slave keeps a record of the binary log coordinates: the file
      name and position within the file that it has read and processed
      from the master. This means that multiple slaves can be connected
      to the master and executing different parts of the same binary
      log. Because the slaves control this process, individual slaves
      can be connected and disconnected from the server without
      affecting the master's operation. Also, because each slave records
      the current position within the binary log, it is possible for
      slaves to be disconnected, reconnect and then resume processing.
    </p><p>
      The master and each slave must be configured with a unique ID
      (using the <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system
      variable). In addition, each slave must be configured with
      information about the master host name, log file name, and
      position within that file. These details can be controlled from
      within a MySQL session using the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE
      MASTER TO</code></a> statement on the slave. The details are stored
      within the slave's master info repository (see
      <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>).
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-howto"></a>17.1.2 Setting Up Binary Log File Position Based Replication</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-howto-masterbaseconfig">17.1.2.1 Setting the Replication Master Configuration</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto-slavebaseconfig">17.1.2.2 Setting the Replication Slave Configuration</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto-repuser">17.1.2.3 Creating a User for Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto-masterstatus">17.1.2.4 Obtaining the Replication Master Binary Log Coordinates</a></span></dt><dt><span class="section"><a href="replication.html#replication-snapshot-method">17.1.2.5 Choosing a Method for Data Snapshots</a></span></dt><dt><span class="section"><a href="replication.html#replication-setup-slaves">17.1.2.6 Setting Up Replication Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto-slaveinit">17.1.2.7 Setting the Master Configuration on the Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-howto-additionalslaves">17.1.2.8 Adding Slaves to a Replication Environment</a></span></dt></dl>
</div>
<p>
      This section describes how to set up a MySQL server to use binary
      log file position based replication. There are a number of
      different methods for setting up replication, and the exact method
      to use depends on how you are setting up replication, and whether
      you already have data within your master database.
    </p><p>
      There are some generic tasks that are common to all setups:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          On the master, you must ensure that binary logging is enabled,
          and configure a unique server ID. This might require a server
          restart. See
          <a class="xref" href="replication.html#replication-howto-masterbaseconfig" title="17.1.2.1 Setting the Replication Master Configuration">Section 17.1.2.1, “Setting the Replication Master Configuration”</a>.
        </p></li><li class="listitem"><p>
          On each slave that you want to connect to the master, you must
          configure a unique server ID. This might require a server
          restart. See
          <a class="xref" href="replication.html#replication-howto-slavebaseconfig" title="17.1.2.2 Setting the Replication Slave Configuration">Section 17.1.2.2, “Setting the Replication Slave Configuration”</a>.
        </p></li><li class="listitem"><p>
          Optionally, create a separate user for your slaves to use
          during authentication with the master when reading the binary
          log for replication. See
          <a class="xref" href="replication.html#replication-howto-repuser" title="17.1.2.3 Creating a User for Replication">Section 17.1.2.3, “Creating a User for Replication”</a>.
        </p></li><li class="listitem"><p>
          Before creating a data snapshot or starting the replication
          process, on the master you should record the current position
          in the binary log. You need this information when configuring
          the slave so that the slave knows where within the binary log
          to start executing events. See
          <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>.
        </p></li><li class="listitem"><p>
          If you already have data on the master and want to use it to
          synchronize the slave, you need to create a data snapshot to
          copy the data to the slave. The storage engine you are using
          has an impact on how you create the snapshot. When you are
          using <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a>, you must stop
          processing statements on the master to obtain a read-lock,
          then obtain its current binary log coordinates and dump its
          data, before permitting the master to continue executing
          statements. If you do not stop the execution of statements,
          the data dump and the master status information will not
          match, resulting in inconsistent or corrupted databases on the
          slaves. For more information on replicating a
          <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a> master, see
          <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>. If you are
          using <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>, you do not need a
          read-lock and a transaction that is long enough to transfer
          the data snapshot is sufficient. For more information, see
          <a class="xref" href="innodb-storage-engine.html#innodb-and-mysql-replication" title="15.19 InnoDB and MySQL Replication">Section 15.19, “InnoDB and MySQL Replication”</a>.
        </p></li><li class="listitem"><p>
          Configure the slave with settings for connecting to the
          master, such as the host name, login credentials, and binary
          log file name and position. See
          <a class="xref" href="replication.html#replication-howto-slaveinit" title="17.1.2.7 Setting the Master Configuration on the Slave">Section 17.1.2.7, “Setting the Master Configuration on the Slave”</a>.
        </p></li><li class="listitem"><p>
          Implement replication-specific security measures on the
          masters and slaves as appropriate for your system. See
          <a class="xref" href="replication.html#replication-security" title="17.3 Replication Security">Section 17.3, “Replication Security”</a>.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
        Certain steps within the setup process require the
        <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a> privilege. If you do not
        have this privilege, it might not be possible to enable
        replication.
</p>
</div>
<p>
      After configuring the basic options, select your scenario:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To set up replication for a fresh installation of a master and
          slaves that contain no data, see
          <a class="xref" href="replication.html#replication-howto-newservers" title="17.1.2.6.1 Setting Up Replication with New Master and Slaves">Section 17.1.2.6.1, “Setting Up Replication with New Master and Slaves”</a>.
        </p></li><li class="listitem"><p>
          To set up replication of a new master using the data from an
          existing MySQL server, see
          <a class="xref" href="replication.html#replication-howto-existingdata" title="17.1.2.6.2 Setting Up Replication with Existing Data">Section 17.1.2.6.2, “Setting Up Replication with Existing Data”</a>.
        </p></li><li class="listitem"><p>
          To add replication slaves to an existing replication
          environment, see
          <a class="xref" href="replication.html#replication-howto-additionalslaves" title="17.1.2.8 Adding Slaves to a Replication Environment">Section 17.1.2.8, “Adding Slaves to a Replication Environment”</a>.
</p></li></ul>
</div>
<p>
      Before administering MySQL replication servers, read this entire
      chapter and try all statements mentioned in
      <a class="xref" href="sql-statements.html#replication-statements-master" title="13.4.1 SQL Statements for Controlling Master Servers">Section 13.4.1, “SQL Statements for Controlling Master Servers”</a>, and
      <a class="xref" href="sql-statements.html#replication-statements-slave" title="13.4.2 SQL Statements for Controlling Slave Servers">Section 13.4.2, “SQL Statements for Controlling Slave Servers”</a>. Also familiarize
      yourself with the replication startup options described in
      <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-masterbaseconfig"></a>17.1.2.1 Setting the Replication Master Configuration</h4>
</div>
</div>
</div>
<p>
        To configure a master to use binary log file position based
        replication, you must ensure that binary logging is enabled, and
        establish a unique server ID. If this has not already been done,
        a server restart is required.
      </p><p>
        Binary logging is required on the master because the binary log
        is the basis for replicating changes from the master to its
        slaves. Binary logging is enabled by default (the
        <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> system variable is set
        to ON). The <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> option
        tells the server what base name to use for binary log files. It
        is recommended that you specify this option to give the binary
        log files a non-default base name, so that if the host name
        changes, you can easily continue to use the same binary log file
        names (see <a class="xref" href="error-handling.html#known-issues" title="B.4.7 Known Issues in MySQL">Section B.4.7, “Known Issues in MySQL”</a>).
      </p><p>
        Each server within a replication topology must be configured
        with a unique server ID, which you can specify using the
        <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable. This
        server ID is used to identify individual servers within the
        replication topology, and must be a positive integer between 1
        and (2<sup>32</sup>)−1. If you set a
        server ID of 0 on a master, it refuses any connections from
        slaves, and if you set a server ID of 0 on a slave, it refuses
        to connect to a master. Other than that, how you organize and
        select the numbers is your choice, so long as each server ID is
        different from every other server ID in use by any other server
        in the replication topology. The
        <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable is
        set to 1 by default. A server can be started with this default
        server ID, but an informational message is issued if you did not
        specify a server ID explicitly.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          The following options also have an impact on the replication
          master:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For the greatest possible durability and consistency in a
              replication setup using
              <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> with transactions, you
              should use
              <code class="literal">innodb_flush_log_at_trx_commit=1</code> and
              <code class="literal">sync_binlog=1</code> in the replication
              master's <code class="filename">my.cnf</code> file.
            </p></li><li class="listitem"><p>
              Ensure that the
              <a class="link" href="server-administration.html#sysvar_skip_networking"><code class="literal">skip_networking</code></a> system
              variable is not enabled on the replication master. If
              networking has been disabled, the slave cannot communicate
              with the master and replication fails.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-slavebaseconfig"></a>17.1.2.2 Setting the Replication Slave Configuration</h4>

</div>

</div>

</div>
<p>
        Each replication slave must have a unique server ID. If this has
        not already been done, this part of slave setup requires a
        server restart.
      </p><p>
        If the slave server ID is not already set, or the current value
        conflicts with the value that you have chosen for the master
        server, shut down the slave server and edit the
        <code class="literal">[mysqld]</code> section of the configuration file to
        specify a unique server ID. For example:
      </p><pre data-lang="ini" class="programlisting">[mysqld]
server-id=2</pre><p>
        After making the changes, restart the server.
      </p><p>
        If you are setting up multiple slaves, each one must have a
        unique <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> value that
        differs from that of the master and from any of the other
        slaves.
      </p><p>
        Binary logging is enabled by default on all servers. A slave is
        not required to have binary logging enabled for replication to
        take place. However, binary logging on a slave means that the
        slave's binary log can be used for data backups and crash
        recovery.
      </p><p>
        Slaves that have binary logging enabled can also be used as part
        of a more complex replication topology. For example, you might
        want to set up replication servers using this chained
        arrangement:
      </p><pre data-lang="none" class="programlisting">A -&gt; B -&gt; C</pre><p>
        Here, <code class="literal">A</code> serves as the master for the slave
        <code class="literal">B</code>, and <code class="literal">B</code> serves as the
        master for the slave <code class="literal">C</code>. For this to work,
        <code class="literal">B</code> must be both a master
        <span class="emphasis"><em>and</em></span> a slave. Updates received from
        <code class="literal">A</code> must be logged by <code class="literal">B</code> to
        its binary log, in order to be passed on to
        <code class="literal">C</code>. In addition to binary logging, this
        replication topology requires the
        <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> system
        variable to be enabled. With slave updates enabled, the slave
        writes updates that are received from a master server and
        performed by the slave's SQL thread to the slave's own binary
        log. <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> system
        variable is enabled by default.
      </p><p>
        If you need to disable binary logging or slave update logging on
        a slave server, you can do this by specifying the
        <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
        and <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a>
        options for the slave.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-repuser"></a>17.1.2.3 Creating a User for Replication</h4>

</div>

</div>

</div>
<p>
        Each slave connects to the master using a MySQL user name and
        password, so there must be a user account on the master that the
        slave can use to connect. The user name is specified by the
        <code class="literal">MASTER_USER</code> option on the <code class="literal">CHANGE
        MASTER TO</code> command when you set up a replication slave.
        Any account can be used for this operation, providing it has
        been granted the <a class="link" href="security.html#priv_replication-slave"><code class="literal">REPLICATION
        SLAVE</code></a> privilege. You can choose to create a different
        account for each slave, or connect to the master using the same
        account for each slave.
      </p><p>
        Although you do not have to create an account specifically for
        replication, you should be aware that the replication user name
        and password are stored in plain text in the master info
        repository table <code class="literal">mysql.slave_master_info</code> (see
        <a class="xref" href="replication.html#slave-logs-status" title="17.2.4.2 Slave Status Logs">Section 17.2.4.2, “Slave Status Logs”</a>). Therefore, you may want to
        create a separate account that has privileges only for the
        replication process, to minimize the possibility of compromise
        to other accounts.
      </p><p>
        To create a new account, use <a class="link" href="sql-statements.html#create-user" title="13.7.1.3 CREATE USER Statement"><code class="literal">CREATE
        USER</code></a>. To grant this account the privileges required
        for replication, use the <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a>
        statement. If you create an account solely for the purposes of
        replication, that account needs only the
        <a class="link" href="security.html#priv_replication-slave"><code class="literal">REPLICATION SLAVE</code></a> privilege. For
        example, to set up a new user, <code class="literal">repl</code>, that can
        connect for replication from any host within the
        <code class="literal">example.com</code> domain, issue these statements on
        the master:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CREATE USER 'repl'@'%.example.com' IDENTIFIED BY '<em class="replaceable"><code>password</code></em>';</code></strong>
mysql&gt; <strong class="userinput"><code>GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%.example.com';</code></strong>
</pre><p>
        See <a class="xref" href="sql-statements.html#account-management-statements" title="13.7.1 Account Management Statements">Section 13.7.1, “Account Management Statements”</a>, for more
        information on statements for manipulation of user accounts.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          To connect to the replication master using a user account that
          authenticates with the
          <code class="literal">caching_sha2_password</code> plugin, you must
          either set up a secure connection as described in
          <a class="xref" href="replication.html#replication-solutions-encrypted-connections" title="17.3.1 Setting Up Replication to Use Encrypted Connections">Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”</a>,
          or enable the unencrypted connection to support password
          exchange using an RSA key pair. The
          <code class="literal">caching_sha2_password</code> authentication plugin
          is the default for new users created from MySQL 8.0 (for
          details, see
          <a class="xref" href="security.html#caching-sha2-pluggable-authentication" title="6.4.1.2 Caching SHA-2 Pluggable Authentication">Section 6.4.1.2, “Caching SHA-2 Pluggable Authentication”</a>).
          If the user account that you create or use for replication (as
          specified by the <code class="literal">MASTER_USER</code> option) uses
          this authentication plugin, and you are not using a secure
          connection, you must enable RSA key pair-based password
          exchange for a successful connection.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-masterstatus"></a>17.1.2.4 Obtaining the Replication Master Binary Log Coordinates</h4>

</div>

</div>

</div>
<p>
        To configure the slave to start the replication process at the
        correct point, you need to note the master's current coordinates
        within its binary log.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          This procedure uses <a class="link" href="sql-statements.html#flush-tables-with-read-lock"><code class="literal">FLUSH TABLES WITH
          READ LOCK</code></a>, which blocks
          <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">COMMIT</code></a> operations for
          <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> tables.
</p>
</div>
<p>
        If you are planning to shut down the master to create a data
        snapshot, you can optionally skip this procedure and instead
        store a copy of the binary log index file along with the data
        snapshot. In that situation, the master creates a new binary log
        file on restart. The master binary log coordinates where the
        slave must start the replication process are therefore the start
        of that new file, which is the next binary log file on the
        master following after the files that are listed in the copied
        binary log index file.
      </p><p>
        To obtain the master binary log coordinates, follow these steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Start a session on the master by connecting to it with the
            command-line client, and flush all tables and block write
            statements by executing the <a class="link" href="sql-statements.html#flush-tables-with-read-lock"><code class="literal">FLUSH
            TABLES WITH READ LOCK</code></a> statement:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>FLUSH TABLES WITH READ LOCK;</code></strong>
</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
              Leave the client from which you issued the
              <a class="link" href="sql-statements.html#flush-tables"><code class="literal">FLUSH TABLES</code></a> statement
              running so that the read lock remains in effect. If you
              exit the client, the lock is released.
</p>
</div>
</li><li class="listitem"><p>
            In a different session on the master, use the
            <a class="link" href="sql-statements.html#show-master-status" title="13.7.7.23 SHOW MASTER STATUS Statement"><code class="literal">SHOW MASTER STATUS</code></a> statement
            to determine the current binary log file name and position:
          </p><pre data-lang="sql" class="programlisting">mysql &gt; <strong class="userinput"><code>SHOW MASTER STATUS;</code></strong>
+------------------+----------+--------------+------------------+
| File             | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000003 | 73       | test         | manual,mysql     |
+------------------+----------+--------------+------------------+
</pre><p>
            The <code class="literal">File</code> column shows the name of the log
            file and the <code class="literal">Position</code> column shows the
            position within the file. In this example, the binary log
            file is <code class="literal">mysql-bin.000003</code> and the position
            is 73. Record these values. You need them later when you are
            setting up the slave. They represent the replication
            coordinates at which the slave should begin processing new
            updates from the master.
          </p><p>
            If the master has been running previously with binary
            logging disabled, the log file name and position values
            displayed by <a class="link" href="sql-statements.html#show-master-status" title="13.7.7.23 SHOW MASTER STATUS Statement"><code class="literal">SHOW MASTER
            STATUS</code></a> or <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump
            --master-data</strong></span></a> will be empty. In that case, the
            values that you need to use later when specifying the
            slave's log file and position are the empty string
            (<code class="literal">''</code>) and <code class="literal">4</code>.
</p></li></ol>
</div>
<p>
        You now have the information you need to enable the slave to
        start reading from the binary log in the correct place to start
        replication.
      </p><p>
        The next step depends on whether you have existing data on the
        master. Choose one of the following options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If you have existing data that needs be to synchronized with
            the slave before you start replication, leave the client
            running so that the lock remains in place. This prevents any
            further changes being made, so that the data copied to the
            slave is in synchrony with the master. Proceed to
            <a class="xref" href="replication.html#replication-snapshot-method" title="17.1.2.5 Choosing a Method for Data Snapshots">Section 17.1.2.5, “Choosing a Method for Data Snapshots”</a>.
          </p></li><li class="listitem"><p>
            If you are setting up a new master and slave replication
            group, you can exit the first session to release the read
            lock. See <a class="xref" href="replication.html#replication-howto-newservers" title="17.1.2.6.1 Setting Up Replication with New Master and Slaves">Section 17.1.2.6.1, “Setting Up Replication with New Master and Slaves”</a> for
            how to proceed.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-snapshot-method"></a>17.1.2.5 Choosing a Method for Data Snapshots</h4>

</div>

</div>

</div>
<p>
        If the master database contains existing data it is necessary to
        copy this data to each slave. There are different ways to dump
        the data from the master database. The following sections
        describe possible options.
      </p><p>
        To select the appropriate method of dumping the database, choose
        between these options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Use the <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> tool to create a dump
            of all the databases you want to replicate. This is the
            recommended method, especially when using
            <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>.
          </p></li><li class="listitem"><p>
            If your database is stored in binary portable files, you can
            copy the raw data files to a slave. This can be more
            efficient than using <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> and
            importing the file on each slave, because it skips the
            overhead of updating indexes as the
            <code class="literal">INSERT</code> statements are replayed. With
            storage engines such as <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>
            this is not recommended.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-howto-mysqldump"></a>17.1.2.5.1 Creating a Data Snapshot Using mysqldump</h5>

</div>

</div>

</div>
<p>
          To create a snapshot of the data in an existing master
          database, use the <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> tool. Once the
          data dump has been completed, import this data into the slave
          before starting the replication process.
        </p><p>
          The following example dumps all databases to a file named
          <code class="filename">dbdump.db</code>, and includes the
          <a class="link" href="programs.html#option_mysqldump_master-data"><code class="option">--master-data</code></a> option which
          automatically appends the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
          TO</code></a> statement required on the slave to start the
          replication process:
        </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqldump --all-databases --master-data &gt; dbdump.db</code></strong>
</pre>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            If you do not use
            <a class="link" href="programs.html#option_mysqldump_master-data"><code class="option">--master-data</code></a>, then it is
            necessary to lock all tables in a separate session manually.
            See <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>.
</p>
</div>
<p>
          It is possible to exclude certain databases from the dump
          using the <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> tool. If you want to
          choose which databases to include in the dump, do not use
          <a class="link" href="programs.html#option_mysqldump_all-databases"><code class="option">--all-databases</code></a>. Choose one
          of these options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Exclude all the tables in the database using
              <a class="link" href="programs.html#option_mysqldump_ignore-table"><code class="option">--ignore-table</code></a> option.

              
            </p></li><li class="listitem"><p>
              Name only those databases which you want dumped using the
              <a class="link" href="programs.html#option_mysqldump_databases"><code class="option">--databases</code></a> option.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
            By default, if GTIDs are in use on the master
            (<a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>),
            <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> includes the GTIDs from the
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on the
            master in the dump output to add them to the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set on the
            slave. If you are dumping only specific databases or tables,
            it is important to note that the value that is included by
            <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> includes the GTIDs of all
            transactions in the
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on the
            master, even those that changed suppressed parts of the
            database, or other databases on the server that were not
            included in the partial dump. Check the description for
            mysqldump's <code class="option">--set-gtid-purged</code> option to
            find the outcome of the default behavior for the MySQL
            Server versions you are using, and how to change the
            behavior if this outcome is not suitable for your situation.
</p>
</div>
<p>
          For more information, see <a class="xref" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program">Section 4.5.4, “<span class="command"><strong>mysqldump</strong></span> — A Database Backup Program”</a>.
        </p><p>
          To import the data, either copy the dump file to the slave, or
          access the file from the master when connecting remotely to
          the slave.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-howto-rawdata"></a>17.1.2.5.2 Creating a Data Snapshot Using Raw Data Files</h5>

</div>

</div>

</div>
<p>
          This section describes how to create a data snapshot using the
          raw files which make up the database.

          

          Employing this method with a table using a storage engine that
          has complex caching or logging algorithms requires extra steps
          to produce a perfect <span class="quote">“<span class="quote">point in time</span>”</span> snapshot:
          the initial copy command could leave out cache information and
          logging updates, even if you have acquired a global read lock.
          How the storage engine responds to this depends on its crash
          recovery abilities.
        </p><p>
          If you use <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> tables, you can
          use the <span class="command"><strong>mysqlbackup</strong></span> command from the MySQL
          Enterprise Backup component to produce a consistent snapshot.
          This command records the log name and offset corresponding to
          the snapshot to be used on the slave. MySQL Enterprise Backup
          is a commercial product that is included as part of a MySQL
          Enterprise subscription. See
          <a class="xref" href="mysql-enterprise.html#mysql-enterprise-backup" title="30.2 MySQL Enterprise Backup Overview">Section 30.2, “MySQL Enterprise Backup Overview”</a> for detailed
          information.
        </p><p>
          

          This method also does not work reliably if the master and
          slave have different values for
          <a class="link" href="server-administration.html#sysvar_ft_stopword_file"><code class="literal">ft_stopword_file</code></a>,
          <a class="link" href="server-administration.html#sysvar_ft_min_word_len"><code class="literal">ft_min_word_len</code></a>, or
          <a class="link" href="server-administration.html#sysvar_ft_max_word_len"><code class="literal">ft_max_word_len</code></a> and you are
          copying tables having full-text indexes.
        </p><p>
          Assuming the above exceptions do not apply to your database,
          use the <a class="link" href="glossary.html#glos_cold_backup" title="cold backup">cold backup</a>
          technique to obtain a reliable binary snapshot of
          <code class="literal">InnoDB</code> tables: do a
          <a class="link" href="glossary.html#glos_slow_shutdown" title="slow shutdown">slow shutdown</a> of the
          MySQL Server, then copy the data files manually.
        </p><p>
          To create a raw data snapshot of
          <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a> tables when your MySQL
          data files exist on a single file system, you can use standard
          file copy tools such as <span class="command"><strong>cp</strong></span> or
          <span class="command"><strong>copy</strong></span>, a remote copy tool such as
          <span class="command"><strong>scp</strong></span> or <span class="command"><strong>rsync</strong></span>, an
          archiving tool such as <span class="command"><strong>zip</strong></span> or
          <span class="command"><strong>tar</strong></span>, or a file system snapshot tool such as
          <span class="command"><strong>dump</strong></span>. If you are replicating only certain
          databases, copy only those files that relate to those tables.
          For <code class="literal">InnoDB</code>, all tables in all databases are
          stored in the <a class="link" href="glossary.html#glos_system_tablespace" title="system tablespace">system
          tablespace</a> files, unless you have the
          <a class="link" href="innodb-storage-engine.html#sysvar_innodb_file_per_table"><code class="option">innodb_file_per_table</code></a> option
          enabled.
        </p><p>
          The following files are not required for replication:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Files relating to the <code class="literal">mysql</code> database.
            </p></li><li class="listitem"><p>
              The master info repository file
              <code class="literal">master.info</code>, if used; the use of this
              file is now deprecated (see <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>).
            </p></li><li class="listitem"><p>
              The master's binary log files, with the exception of the
              binary log index file if you are going to use this to
              locate the master binary log coordinates for the slave.
            </p></li><li class="listitem"><p>
              Any relay log files.
</p></li></ul>
</div>
<p>
          Depending on whether you are using <code class="literal">InnoDB</code>
          tables or not, choose one of the following:
        </p><p>
          If you are using <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> tables,
          and also to get the most consistent results with a raw data
          snapshot, shut down the master server during the process, as
          follows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Acquire a read lock and get the master's status. See
              <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>.
            </p></li><li class="listitem"><p>
              In a separate session, shut down the master server:
            </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin shutdown</code></strong>
</pre></li><li class="listitem"><p>
              Make a copy of the MySQL data files. The following
              examples show common ways to do this. You need to choose
              only one of them:
            </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>tar cf <em class="replaceable"><code>/tmp/db.tar</code></em> <em class="replaceable"><code>./data</code></em></code></strong>
shell&gt; <strong class="userinput"><code>zip -r <em class="replaceable"><code>/tmp/db.zip</code></em> <em class="replaceable"><code>./data</code></em></code></strong>
shell&gt; <strong class="userinput"><code>rsync --recursive <em class="replaceable"><code>./data</code></em> <em class="replaceable"><code>/tmp/dbdata</code></em></code></strong>
</pre></li><li class="listitem"><p>
              Restart the master server.
</p></li></ol>
</div>
<p>
          If you are not using <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>
          tables, you can get a snapshot of the system from a master
          without shutting down the server as described in the following
          steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Acquire a read lock and get the master's status. See
              <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>.
            </p></li><li class="listitem"><p>
              Make a copy of the MySQL data files. The following
              examples show common ways to do this. You need to choose
              only one of them:
            </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>tar cf <em class="replaceable"><code>/tmp/db.tar</code></em> <em class="replaceable"><code>./data</code></em></code></strong>
shell&gt; <strong class="userinput"><code>zip -r <em class="replaceable"><code>/tmp/db.zip</code></em> <em class="replaceable"><code>./data</code></em></code></strong>
shell&gt; <strong class="userinput"><code>rsync --recursive <em class="replaceable"><code>./data</code></em> <em class="replaceable"><code>/tmp/dbdata</code></em></code></strong>
</pre></li><li class="listitem"><p>
              In the client where you acquired the read lock, release
              the lock:
            </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>UNLOCK TABLES;</code></strong>
</pre></li></ol>
</div>
<p>
          Once you have created the archive or copy of the database,
          copy the files to each slave before starting the slave
          replication process.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-setup-slaves"></a>17.1.2.6 Setting Up Replication Slaves</h4>

</div>

</div>

</div>
<p>
        The following sections describe how to set up slaves. Before you
        proceed, ensure that you have:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Configured the MySQL master with the necessary configuration
            properties. See
            <a class="xref" href="replication.html#replication-howto-masterbaseconfig" title="17.1.2.1 Setting the Replication Master Configuration">Section 17.1.2.1, “Setting the Replication Master Configuration”</a>.
          </p></li><li class="listitem"><p>
            Obtained the master status information, or a copy of the
            master's binary log index file made during a shutdown for
            the data snapshot. See
            <a class="xref" href="replication.html#replication-howto-masterstatus" title="17.1.2.4 Obtaining the Replication Master Binary Log Coordinates">Section 17.1.2.4, “Obtaining the Replication Master Binary Log Coordinates”</a>.
          </p></li><li class="listitem"><p>
            On the master, released the read lock:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>UNLOCK TABLES;</code></strong>
</pre></li><li class="listitem"><p>
            On the slave, edited the MySQL configuration. See
            <a class="xref" href="replication.html#replication-howto-slavebaseconfig" title="17.1.2.2 Setting the Replication Slave Configuration">Section 17.1.2.2, “Setting the Replication Slave Configuration”</a>.
</p></li></ul>
</div>
<p>
        The next steps depend on whether you have existing data to
        import to the slave or not. See
        <a class="xref" href="replication.html#replication-snapshot-method" title="17.1.2.5 Choosing a Method for Data Snapshots">Section 17.1.2.5, “Choosing a Method for Data Snapshots”</a> for more
        information. Choose one of the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If you do not have a snapshot of a database to import, see
            <a class="xref" href="replication.html#replication-howto-newservers" title="17.1.2.6.1 Setting Up Replication with New Master and Slaves">Section 17.1.2.6.1, “Setting Up Replication with New Master and Slaves”</a>.
          </p></li><li class="listitem"><p>
            If you have a snapshot of a database to import, see
            <a class="xref" href="replication.html#replication-howto-existingdata" title="17.1.2.6.2 Setting Up Replication with Existing Data">Section 17.1.2.6.2, “Setting Up Replication with Existing Data”</a>.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-howto-newservers"></a>17.1.2.6.1 Setting Up Replication with New Master and Slaves</h5>

</div>

</div>

</div>
<p>
          When there is no snapshot of a previous database to import,
          configure the slave to start the replication from the new
          master.
        </p><p>
          To set up replication between a master and a new slave:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Start up the MySQL slave.
            </p></li><li class="listitem"><p>
              Execute a <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
              statement to set the master replication server
              configuration. See
              <a class="xref" href="replication.html#replication-howto-slaveinit" title="17.1.2.7 Setting the Master Configuration on the Slave">Section 17.1.2.7, “Setting the Master Configuration on the Slave”</a>.
</p></li></ol>
</div>
<p>
          Perform these slave setup steps on each slave.
        </p><p>
          This method can also be used if you are setting up new servers
          but have an existing dump of the databases from a different
          server that you want to load into your replication
          configuration. By loading the data into a new master, the data
          is automatically replicated to the slaves.
        </p><p>
          If you are setting up a new replication environment using the
          data from a different existing database server to create a new
          master, run the dump file generated from that server on the
          new master. The database updates are automatically propagated
          to the slaves:
        </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysql -h master &lt; fulldb.dump</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-howto-existingdata"></a>17.1.2.6.2 Setting Up Replication with Existing Data</h5>

</div>

</div>

</div>
<p>
          When setting up replication with existing data, transfer the
          snapshot from the master to the slave before starting
          replication. The process for importing data to the slave
          depends on how you created the snapshot of data on the master.
        </p><p>
          Choose one of the following:
        </p><p>
          If you used <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Start the slave, using the
              <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option
              so that replication does not start.
            </p></li><li class="listitem"><p>
              Import the dump file:
            </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysql &lt; fulldb.dump</code></strong>
</pre></li></ol>
</div>
<p>
          If you created a snapshot using the raw data files:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Extract the data files into your slave data directory. For
              example:
            </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>tar xvf dbdump.tar</code></strong>
</pre><p>
              You may need to set permissions and ownership on the files
              so that the slave server can access and modify them.
            </p></li><li class="listitem"><p>
              Start the slave, using the
              <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option
              so that replication does not start.
            </p></li><li class="listitem"><p>
              Configure the slave with the replication coordinates from
              the master. This tells the slave the binary log file and
              position within the file where replication needs to start.
              Also, configure the slave with the login credentials and
              host name of the master. For more information on the
              <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
              required, see
              <a class="xref" href="replication.html#replication-howto-slaveinit" title="17.1.2.7 Setting the Master Configuration on the Slave">Section 17.1.2.7, “Setting the Master Configuration on the Slave”</a>.
            </p></li><li class="listitem"><p>
              Start the slave threads:
            </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre></li></ol>
</div>
<p>
          After you have performed this procedure, the slave connects to
          the master and replicates any updates that have occurred on
          the master since the snapshot was taken. Error messages are
          issued to the slave's error log if it is not able to replicate
          for any reason.
        </p><p>
          The slave uses information logged in its master info log and
          relay log info log to keep track of how much of the
          master's binary log it has processed. From MySQL 8.0, by
          default, the repositories for these slave status logs are
          tables named <code class="literal">slave_master_info</code> and
          <code class="literal">slave_relay_log_info</code> in the
          <code class="literal">mysql</code> database. The alternative settings
          <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository=FILE</code></a>
          and
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=FILE</code></a>,
          where the repositories are files named
          <code class="filename">master.info</code> and
          <code class="filename">relay-log.info</code> in the data directory, are
          now deprecated and will be removed in a future release.
        </p><p>
          Do <span class="emphasis"><em>not</em></span> remove or edit these tables (or
          files, if used) unless you know exactly what you are doing and
          fully understand the implications. Even in that case, it is
          preferred that you use the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
          TO</code></a> statement to change replication parameters. The
          slave uses the values specified in the statement to update the
          slave status logs automatically. See
          <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>, for more information.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            The contents of the master info log override some of the
            server options specified on the command line or in
            <code class="filename">my.cnf</code>. See
            <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>, for more details.
</p>
</div>
<p>
          A single snapshot of the master suffices for multiple slaves.
          To set up additional slaves, use the same master snapshot and
          follow the slave portion of the procedure just described.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-slaveinit"></a>17.1.2.7 Setting the Master Configuration on the Slave</h4>

</div>

</div>

</div>
<p>
        To set up the slave to communicate with the master for
        replication, configure the slave with the necessary connection
        information. To do this, execute the following statement on the
        slave, replacing the option values with the actual values
        relevant to your system:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO</code></strong>
    -&gt;     <strong class="userinput"><code>MASTER_HOST='<em class="replaceable"><code>master_host_name</code></em>',</code></strong>
    -&gt;     <strong class="userinput"><code>MASTER_USER='<em class="replaceable"><code>replication_user_name</code></em>',</code></strong>
    -&gt;     <strong class="userinput"><code>MASTER_PASSWORD='<em class="replaceable"><code>replication_password</code></em>',</code></strong>
    -&gt;     <strong class="userinput"><code>MASTER_LOG_FILE='<em class="replaceable"><code>recorded_log_file_name</code></em>',</code></strong>
    -&gt;     <strong class="userinput"><code>MASTER_LOG_POS=<em class="replaceable"><code>recorded_log_position</code></em>;</code></strong>
</pre>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          Replication cannot use Unix socket files. You must be able to
          connect to the master MySQL server using TCP/IP.
</p>
</div>
<p>
        The <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
        has other options as well. For example, it is possible to set up
        secure replication using SSL. For a full list of options, and
        information about the maximum permissible length for the
        string-valued options, see <a class="xref" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement">Section 13.4.2.1, “CHANGE MASTER TO Statement”</a>.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          As noted in
          <a class="xref" href="replication.html#replication-howto-repuser" title="17.1.2.3 Creating a User for Replication">Section 17.1.2.3, “Creating a User for Replication”</a>, if you
          are not using a secure connection and the user account named
          in the <code class="literal">MASTER_USER</code> option authenticates
          with the <code class="literal">caching_sha2_password</code> plugin (the
          default from MySQL 8.0), you must specify the
          <code class="literal">MASTER_PUBLIC_KEY_PATH</code> or
          <code class="literal">GET_MASTER_PUBLIC_KEY</code> option in the
          <code class="literal">CHANGE MASTER TO</code> statement to enable RSA
          key pair-based password exchange.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-howto-additionalslaves"></a>17.1.2.8 Adding Slaves to a Replication Environment</h4>

</div>

</div>

</div>
<p>
        You can add another slave to an existing replication
        configuration without stopping the master. To do this, you can
        set up the new slave by copying the data directory of an
        existing slave, and giving the new slave a different server ID
        (which is user-specified) and server UUID (which is generated at
        startup).
      </p><p>
        To duplicate an existing slave:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Stop the existing slave and record the slave status
            information, particularly the master binary log file and
            relay log file positions. You can view the slave status
            either in the Performance Schema replication tables (see
            <a class="xref" href="performance-schema.html#performance-schema-replication-tables" title="26.12.11 Performance Schema Replication Tables">Section 26.12.11, “Performance Schema Replication Tables”</a>), or
            by issuing <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>
            as follows:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP SLAVE;</code></strong>
mysql&gt; <strong class="userinput"><code>SHOW SLAVE STATUS\G</code></strong>
</pre></li><li class="listitem"><p>
            Shut down the existing slave:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin shutdown</code></strong>
</pre></li><li class="listitem"><p>
            Copy the data directory from the existing slave to the new
            slave, including the log files and relay log files. You can
            do this by creating an archive using <span class="command"><strong>tar</strong></span>
            or <code class="literal">WinZip</code>, or by performing a direct copy
            using a tool such as <span class="command"><strong>cp</strong></span> or
            <span class="command"><strong>rsync</strong></span>.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>

<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
                  Before copying, verify that all the files relating to
                  the existing slave actually are stored in the data
                  directory. For example, the <code class="literal">InnoDB</code>
                  system tablespace, undo tablespace, and redo log might
                  be stored in an alternative location.
                  <code class="literal">InnoDB</code> tablespace files and
                  file-per-table tablespaces might have been created in
                  other directories. The binary logs and relay logs for
                  the slave might be in their own directories outside
                  the data directory. Check through the system variables
                  that are set for the existing slave and look for any
                  alternative paths that have been specified. If you
                  find any, copy these directories over as well.
                </p></li><li class="listitem"><p>
                  During copying, if files have been used for the master
                  info and relay log info repositories (see
                  <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>), ensure that you also
                  copy these files from the existing slave to the new
                  slave. If tables have been used for the repositories,
                  which is the default from MySQL 8.0, the tables are in
                  the data directory.
                </p></li><li class="listitem"><p>
                  After copying, delete the
                  <code class="filename">auto.cnf</code> file from the copy of
                  the data directory on the new slave, so that the new
                  slave is started with a different generated server
                  UUID. The server UUID must be unique.
</p></li></ul>
</div>

</div>
<p>
            A common problem that is encountered when adding new
            replication slaves is that the new slave fails with a series
            of warning and error messages like these:
          </p><pre data-lang="none" class="programlisting">071118 16:44:10 [Warning] Neither --relay-log nor --relay-log-index were used; so
replication may break when this MySQL server acts as a slave and has his hostname
changed!! Please use '--relay-log=<em class="replaceable"><code>new_slave_hostname</code></em>-relay-bin' to avoid this problem.
<span class="errortext">071118 16:44:10 [ERROR] Failed to open the relay log './<em class="replaceable"><code>old_slave_hostname</code></em>-relay-bin.003525'
(relay_log_pos 22940879)</span>
071118 16:44:10 <span class="errortext">[ERROR] Could not find target log during relay log initialization</span>
071118 16:44:10 <span class="errortext">[ERROR] Failed to initialize the master info structure</span>
</pre><p>
            This situation can occur if the
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable
            is not specified, as the relay log files contain the host
            name as part of their file names. This is also true of the
            relay log index file if the
            <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
            variable is not used. For more information about these
            variables, see <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
          </p><p>
            To avoid this problem, use the same value for
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> on the new slave
            that was used on the existing slave. If this option was not
            set explicitly on the existing slave, use
            <code class="literal"><em class="replaceable"><code>existing_slave_hostname</code></em>-relay-bin</code>.
            If this is not possible, copy the existing slave's relay log
            index file to the new slave and set the
            <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
            variable on the new slave to match what was used on the
            existing slave. If this option was not set explicitly on the
            existing slave, use
            <code class="literal"><em class="replaceable"><code>existing_slave_hostname</code></em>-relay-bin.index</code>.
            Alternatively, if you have already tried to start the new
            slave after following the remaining steps in this section
            and have encountered errors like those described previously,
            then perform the following steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="a"><li class="listitem"><p>
                If you have not already done so, issue
                <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> on the new
                slave.
              </p><p>
                If you have already started the existing slave again,
                issue <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> on the
                existing slave as well.
              </p></li><li class="listitem"><p>
                Copy the contents of the existing slave's relay log
                index file into the new slave's relay log index file,
                making sure to overwrite any content already in the
                file.
              </p></li><li class="listitem"><p>
                Proceed with the remaining steps in this section.
</p></li></ol>
</div>
</li><li class="listitem"><p>
            When copying is complete, restart the existing slave.
          </p></li><li class="listitem"><p>
            On the new slave, edit the configuration and give the new
            slave a unique server ID (using the
            <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable)
            that is not used by the master or any of the existing
            slaves.
          </p></li><li class="listitem"><p>
            Start the new slave server, specifying the
            <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option so
            that replication does not start yet. Use the Performance
            Schema replication tables or issue <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW
            SLAVE STATUS</code></a> to confirm that the new slave has the
            correct settings when compared with the existing slave. Also
            display the server ID and server UUID and verify that these
            are correct and unique for the new slave.
          </p></li><li class="listitem"><p>
            Start the slave threads by issuing a
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong></pre><p>
            The new slave now uses the information in its master info
            repository to start the replication process.
</p></li></ol>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-gtids"></a>17.1.3 Replication with Global Transaction Identifiers</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-gtids-concepts">17.1.3.1 GTID Format and Storage</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-lifecycle">17.1.3.2 GTID Life Cycle</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-auto-positioning">17.1.3.3 GTID Auto-Positioning</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-howto">17.1.3.4 Setting Up Replication Using GTIDs</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-failover">17.1.3.5 Using GTIDs for Failover and Scaleout</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-restrictions">17.1.3.6 Restrictions on Replication with GTIDs</a></span></dt><dt><span class="section"><a href="replication.html#replication-gtids-functions">17.1.3.7 Stored Function Examples to Manipulate GTIDs</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444271737856"></a><p>
    This section explains transaction-based replication using
    <span class="firstterm">global transaction identifiers</span>
    (GTIDs). When using GTIDs, each transaction can be identified and
    tracked as it is committed on the originating server and applied by
    any slaves; this means that it is not necessary when using GTIDs to
    refer to log files or positions within those files when starting a
    new slave or failing over to a new master, which greatly simplifies
    these tasks. Because GTID-based replication is completely
    transaction-based, it is simple to determine whether masters and
    slaves are consistent; as long as all transactions committed on a
    master are also committed on a slave, consistency between the two is
    guaranteed. You can use either statement-based or row-based
    replication with GTIDs (see <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>);
    however, for best results, we recommend that you use the row-based
    format.
  </p><p>
    GTIDs are always preserved between master and slave. This means that
    you can always determine the source for any transaction applied on
    any slave by examining its binary log. In addition, once a
    transaction with a given GTID is committed on a given server, any
    subsequent transaction having the same GTID is ignored by that
    server. Thus, a transaction committed on the master can be applied
    no more than once on the slave, which helps to guarantee
    consistency.
  </p><p>
    This section discusses the following topics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        How GTIDs are defined and created, and how they are represented
        in a MySQL server (see
        <a class="xref" href="replication.html#replication-gtids-concepts" title="17.1.3.1 GTID Format and Storage">Section 17.1.3.1, “GTID Format and Storage”</a>).
      </p></li><li class="listitem"><p>
        The life cycle of a GTID (see
        <a class="xref" href="replication.html#replication-gtids-lifecycle" title="17.1.3.2 GTID Life Cycle">Section 17.1.3.2, “GTID Life Cycle”</a>).
      </p></li><li class="listitem"><p>
        The auto-positioning function for synchronizing a slave and
        master that use GTIDs (see
        <a class="xref" href="replication.html#replication-gtids-auto-positioning" title="17.1.3.3 GTID Auto-Positioning">Section 17.1.3.3, “GTID Auto-Positioning”</a>).
      </p></li><li class="listitem"><p>
        A general procedure for setting up and starting GTID-based
        replication (see <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a>).
      </p></li><li class="listitem"><p>
        Suggested methods for provisioning new replication servers when
        using GTIDs (see <a class="xref" href="replication.html#replication-gtids-failover" title="17.1.3.5 Using GTIDs for Failover and Scaleout">Section 17.1.3.5, “Using GTIDs for Failover and Scaleout”</a>).
      </p></li><li class="listitem"><p>
        Restrictions and limitations that you should be aware of when
        using GTID-based replication (see
        <a class="xref" href="replication.html#replication-gtids-restrictions" title="17.1.3.6 Restrictions on Replication with GTIDs">Section 17.1.3.6, “Restrictions on Replication with GTIDs”</a>).
      </p></li><li class="listitem"><p>
        Stored functions that you can use to work with GTIDs (see
        <a class="xref" href="replication.html#replication-gtids-functions" title="17.1.3.7 Stored Function Examples to Manipulate GTIDs">Section 17.1.3.7, “Stored Function Examples to Manipulate GTIDs”</a>).
</p></li></ul>
</div>
<p>
    For information about MySQL Server options and variables relating to
    GTID-based replication, see
    <a class="xref" href="replication.html#replication-options-gtids" title="17.1.6.5 Global Transaction ID System Variables">Section 17.1.6.5, “Global Transaction ID System Variables”</a>. See also
    <a class="xref" href="functions.html#gtid-functions" title="12.18 Functions Used with Global Transaction Identifiers (GTIDs)">Section 12.18, “Functions Used with Global Transaction Identifiers (GTIDs)”</a>, which describes SQL functions
    supported by MySQL 8.0 for use with GTIDs.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-concepts"></a>17.1.3.1 GTID Format and Storage</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444271717456"></a><p>
      A global transaction identifier (GTID) is a unique identifier
      created and associated with each transaction committed on the
      server of origin (the master). This identifier is unique not only
      to the server on which it originated, but is unique across all
      servers in a given replication topology.
    </p><p>
      GTID assignment distinguishes between client transactions, which
      are committed on the master, and replicated transactions, which
      are reproduced on a slave. When a client transaction is committed
      on the master, it is assigned a new GTID, provided that the
      transaction was written to the binary log. Client transactions are
      guaranteed to have monotonically increasing GTIDs without gaps
      between the generated numbers. If a client transaction is not
      written to the binary log (for example, because the transaction
      was filtered out, or the transaction was read-only), it is not
      assigned a GTID on the server of origin.
    </p><p>
      Replicated transactions retain the same GTID that was assigned to
      the transaction on the server of origin. The GTID is present
      before the replicated transaction begins to execute, and is
      persisted even if the replicated transaction is not written to the
      binary log on the slave, or is filtered out on the slave. The
      MySQL system table <code class="literal">mysql.gtid_executed</code> is used
      to preserve the assigned GTIDs of all the transactions applied on
      a MySQL server, except those that are stored in a currently active
      binary log file.
    </p><p>
      The auto-skip function for GTIDs means that a transaction
      committed on the master can be applied no more than once on the
      slave, which helps to guarantee consistency. Once a transaction
      with a given GTID has been committed on a given server, any
      attempt to execute a subsequent transaction with the same GTID is
      ignored by that server. No error is raised, and no statement in
      the transaction is executed.
    </p><p>
      If a transaction with a given GTID has started to execute on a
      server, but has not yet committed or rolled back, any attempt to
      start a concurrent transaction on the server with the same GTID
      will block. The server neither begins to execute the concurrent
      transaction nor returns control to the client. Once the first
      attempt at the transaction commits or rolls back, concurrent
      sessions that were blocking on the same GTID may proceed. If the
      first attempt rolled back, one concurrent session proceeds to
      attempt the transaction, and any other concurrent sessions that
      were blocking on the same GTID remain blocked. If the first
      attempt committed, all the concurrent sessions stop being blocked,
      and auto-skip all the statements of the transaction.
    </p><p>
      A GTID is represented as a pair of coordinates, separated by a
      colon character (<code class="literal">:</code>), as shown here:
    </p><pre data-lang="ini" class="programlisting">GTID = <em class="replaceable"><code>source_id</code></em>:<em class="replaceable"><code>transaction_id</code></em>
</pre><p>
      The <em class="replaceable"><code>source_id</code></em> identifies the
      originating server. Normally, the master's
      <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> is used for this
      purpose. The <em class="replaceable"><code>transaction_id</code></em> is a
      sequence number determined by the order in which the transaction
      was committed on the master. For example, the first transaction to
      be committed has <code class="literal">1</code> as its
      <em class="replaceable"><code>transaction_id</code></em>, and the tenth
      transaction to be committed on the same originating server is
      assigned a <em class="replaceable"><code>transaction_id</code></em> of
      <code class="literal">10</code>. It is not possible for a transaction to
      have <code class="literal">0</code> as a sequence number in a GTID. For
      example, the twenty-third transaction to be committed originally
      on the server with the UUID
      <code class="literal">3E11FA47-71CA-11E1-9E33-C80AA9429562</code> has this
      GTID:
    </p><pre data-lang="none" class="programlisting">3E11FA47-71CA-11E1-9E33-C80AA9429562:23</pre><p>
      The GTID for a transaction is shown in the output from
      <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, and it is used to identify an
      individual transaction in the Performance Schema replication
      status tables, for example,
      <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>.
      The value stored by the <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>
      system variable (<code class="literal">@@GLOBAL.gtid_next</code>) is a
      single GTID.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-gtids-concepts-gtid-sets"></a>GTID Sets</h5>
</div>
</div>
</div>
<a class="indexterm" name="idm46444271692688"></a><p>
        A GTID set is a set comprising one or more single GTIDs or
        ranges of GTIDs. GTID sets are used in a MySQL server in several
        ways. For example, the values stored by the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system variables
        are GTID sets. The <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
        clauses <code class="literal">UNTIL SQL_BEFORE_GTIDS</code> and
        <code class="literal">UNTIL SQL_AFTER_GTIDS</code> can be used to make a
        slave process transactions only up to the first GTID in a GTID
        set, or stop after the last GTID in a GTID set. The built-in
        functions <a class="link" href="functions.html#function_gtid-subset"><code class="literal">GTID_SUBSET()</code></a> and
        <a class="link" href="functions.html#function_gtid-subtract"><code class="literal">GTID_SUBTRACT()</code></a> require GTID sets
        as input.
      </p><p>
        A range of GTIDs originating from the same server can be
        collapsed into a single expression, as shown here:
      </p><pre data-lang="none" class="programlisting">3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5</pre><p>
        The above example represents the first through fifth
        transactions originating on the MySQL server whose
        <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> is
        <code class="literal">3E11FA47-71CA-11E1-9E33-C80AA9429562</code>.
        Multiple single GTIDs or ranges of GTIDs originating from the
        same server can also be included in a single expression, with
        the GTIDs or ranges separated by colons, as in the following
        example:
      </p><pre data-lang="none" class="programlisting">3E11FA47-71CA-11E1-9E33-C80AA9429562:1-3:11:47-49</pre><p>
        A GTID set can include any combination of single GTIDs and
        ranges of GTIDs, and it can include GTIDs originating from
        different servers. This example shows the GTID set stored in the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
        (<code class="literal">@@GLOBAL.gtid_executed</code>) of a slave that has
        applied transactions from more than one master:
      </p><pre data-lang="none" class="programlisting">2174B383-5441-11E8-B90A-C80AA9429562:1-3, 24DA167-0C0C-11E8-8442-00059A3C7B00:1-19</pre><p>
        When GTID sets are returned from server variables, UUIDs are in
        alphabetical order, and numeric intervals are merged and in
        ascending order.
      </p><p>
        The syntax for a GTID set is as follows:
      </p><pre data-lang="sql" class="programlisting"><em class="replaceable"><code>gtid_set</code></em>:
    <em class="replaceable"><code>uuid_set</code></em> [, <em class="replaceable"><code>uuid_set</code></em>] ...
    | ''

<em class="replaceable"><code>uuid_set</code></em>:
    <em class="replaceable"><code>uuid</code></em>:<em class="replaceable"><code>interval</code></em>[:<em class="replaceable"><code>interval</code></em>]...

<em class="replaceable"><code>uuid</code></em>:
    <em class="replaceable"><code>hhhhhhhh</code></em>-<em class="replaceable"><code>hhhh</code></em>-<em class="replaceable"><code>hhhh</code></em>-<em class="replaceable"><code>hhhh</code></em>-<em class="replaceable"><code>hhhhhhhhhhhh</code></em>

<em class="replaceable"><code>h</code></em>:
    [0-9|A-F]

<em class="replaceable"><code>interval</code></em>:
    <em class="replaceable"><code>n</code></em>[-<em class="replaceable"><code>n</code></em>]

    (<em class="replaceable"><code>n</code></em> &gt;= 1)
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-gtids-gtid-executed-table"></a>mysql.gtid_executed Table</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271663136"></a><a class="indexterm" name="idm46444271662048"></a><a class="indexterm" name="idm46444271660560"></a><a class="indexterm" name="idm46444271659072"></a><a class="indexterm" name="idm46444271657584"></a><p>
        GTIDs are stored in a table named
        <code class="literal">gtid_executed</code>, in the
        <code class="literal">mysql</code> database. A row in this table contains,
        for each GTID or set of GTIDs that it represents, the UUID of
        the originating server, and the starting and ending transaction
        IDs of the set; for a row referencing only a single GTID, these
        last two values are the same.
      </p><p>
        The <code class="literal">mysql.gtid_executed</code> table is created (if
        it does not already exist) when MySQL Server is installed or
        upgraded, using a <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a>
        statement similar to that shown here:
      </p><pre data-lang="sql" class="programlisting">CREATE TABLE gtid_executed (
    source_uuid CHAR(36) NOT NULL,
    interval_start BIGINT(20) NOT NULL,
    interval_end BIGINT(20) NOT NULL,                                                                                                                                                                                  
    PRIMARY KEY (source_uuid, interval_start)
)      </pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          As with other MySQL system tables, do not attempt to create or
          modify this table yourself.
</p>
</div>
<a class="indexterm" name="idm46444271648416"></a><a class="indexterm" name="idm46444271646912"></a><p>
        The <code class="literal">mysql.gtid_executed</code> table is provided for
        internal use by the MySQL server. It enables a slave to use
        GTIDs when binary logging is disabled on the slave, and it
        enables retention of the GTID state when the binary logs have
        been lost. Note that the <code class="literal">mysql.gtid_executed</code>
        table is cleared if you issue <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET
        MASTER</code></a>.
      </p><p>
        GTIDs are stored in the <code class="literal">mysql.gtid_executed</code>
        table only when <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is
        <code class="literal">ON</code> or <code class="literal">ON_PERMISSIVE</code>. If
        binary logging is disabled (<code class="literal">log_bin</code> is
        <code class="literal">OFF</code>), or if
        <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> is disabled,
        the server stores the GTID belonging to each transaction
        together with the transaction in the
        <code class="literal">mysql.gtid_executed</code> table at transaction
        commit time. In addition, the table is compressed periodically
        at a user-configurable rate, as described in
        <a class="xref" href="replication.html#replication-gtids-gtid-executed-table-compression" title="mysql.gtid_executed Table Compression">mysql.gtid_executed Table Compression</a>.
      </p><p>
        If binary logging is enabled (<code class="literal">log_bin</code> is
        <code class="literal">ON</code>), from MySQL 8.0.17 for the
        <code class="literal">InnoDB</code> storage engine only, the server
        updates the <code class="literal">mysql.gtid_executed</code> table in the
        same way as when binary logging or slave update logging is
        disabled, storing the GTID for each transaction at transaction
        commit time. However, in releases before MySQL 8.0.17, and for
        other storage engines, the server only updates the
        <code class="literal">mysql.gtid_executed</code> table when the binary log
        is rotated or the server is shut down. At these times, the
        server writes GTIDs for all transactions that were written into
        the previous binary log into the
        <code class="literal">mysql.gtid_executed</code> table. This situation
        applies on a replication master prior to MySQL 8.0.17, or on a
        replication slave prior to MySQL 8.0.17 where binary logging is
        enabled, or with storage engines other than
        <code class="literal">InnoDB</code>, it has the following consequences:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            In the event of the server stopping unexpectedly, the set of
            GTIDs from the current binary log file is not saved in the
            <code class="literal">mysql.gtid_executed</code> table. These GTIDs
            are added to the table from the binary log file during
            recovery so that replication can continue. The exception to
            this is if you disable binary logging when the server is
            restarted (using
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            or
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--disable-log-bin</code></a>).
            In that case, the server cannot access the binary log file
            to recover the GTIDs, so replication cannot be started.
          </p></li><li class="listitem"><p>
            The <code class="literal">mysql.gtid_executed</code> table does not
            hold a complete record of the GTIDs for all executed
            transactions. That information is provided by the global
            value of the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
            system variable. In releases before MySQL 8.0.17 and with
            storage engines other than <code class="literal">InnoDB</code>, always
            use <code class="literal">@@GLOBAL.gtid_executed</code>, which is
            updated after every commit, to represent the GTID state for
            the MySQL server, instead of querying the
            <code class="literal">mysql.gtid_executed</code> table.
</p></li></ul>
</div>
<p>
        The MySQL server can write to the
        <code class="literal">mysql.gtid_executed</code> table even when the
        server is in read only or super read only mode. In releases
        before MySQL 8.0.17, this ensures that the binary log file can
        still be rotated in these modes. If the
        <code class="literal">mysql.gtid_executed</code> table cannot be accessed
        for writes, and the binary log file is rotated for any reason
        other than reaching the maximum file size
        (<a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>), the current
        binary log file continues to be used. An error message is
        returned to the client that requested the rotation, and a
        warning is logged on the server. If the
        <code class="literal">mysql.gtid_executed</code> table cannot be accessed
        for writes and <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>
        is reached, the server responds according to its
        <a class="link" href="replication.html#sysvar_binlog_error_action"><code class="literal">binlog_error_action</code></a> setting. If
        <code class="literal">IGNORE_ERROR</code> is set, an error is logged on
        the server and binary logging is halted, or if
        <code class="literal">ABORT_SERVER</code> is set, the server shuts down.

</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-gtids-gtid-executed-table-compression"></a>mysql.gtid_executed Table Compression</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271607904"></a><p>
        Over the course of time, the
        <code class="literal">mysql.gtid_executed</code> table can become filled
        with many rows referring to individual GTIDs that originate on
        the same server, and whose transaction IDs make up a range,
        similar to what is shown here:
      </p><pre data-lang="sql" class="programlisting">+--------------------------------------+----------------+--------------+
| source_uuid                          | interval_start | interval_end |
|--------------------------------------+----------------+--------------|
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 37             | 37           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 38             | 38           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 39             | 39           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 40             | 40           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 41             | 41           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 42             | 42           |
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 43             | 43           |
...</pre><p>
        To save space, the MySQL server compresses the
        <code class="literal">mysql.gtid_executed</code> table periodically by
        replacing each such set of rows with a single row that spans the
        entire interval of transaction identifiers, like this:
      </p><pre data-lang="none" class="programlisting">+--------------------------------------+----------------+--------------+
| source_uuid                          | interval_start | interval_end |
|--------------------------------------+----------------+--------------|
| 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 37             | 43           |
...</pre><p>
        You can control the number of transactions that are allowed to
        elapse before the table is compressed, and thus the compression
        rate, by setting the
        <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
        system variable. This variable's default value is 1000,
        meaning that by default, compression of the table is performed
        after each 1000 transactions. Setting
        <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
        to 0 prevents the compression from being performed at all, and
        you should be prepared for a potentially large increase in the
        amount of disk space that may be required by the
        <code class="literal">gtid_executed</code> table if you do this.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          When binary logging is enabled, the value of
          <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
          is <span class="emphasis"><em>not</em></span> used and the
          <code class="literal">mysql.gtid_executed</code> table is compressed on
          each binary log rotation.
</p>
</div>
<a class="indexterm" name="idm46444271592592"></a><a class="indexterm" name="idm46444271591504"></a><a class="indexterm" name="idm46444271589984"></a><p>
        Compression of the <code class="literal">mysql.gtid_executed</code> table
        is performed by a dedicated foreground thread named
        <code class="literal">thread/sql/compress_gtid_table</code>. This thread
        is not listed in the output of <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
        PROCESSLIST</code></a>, but it can be viewed as a row in the
        <a class="link" href="performance-schema.html#threads-table" title="26.12.19.5 The threads Table"><code class="literal">threads</code></a> table, as shown here:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT * FROM performance_schema.threads WHERE NAME LIKE '%gtid%'\G</code></strong>
*************************** 1. row ***************************
          THREAD_ID: 26
               NAME: thread/sql/compress_gtid_table
               TYPE: FOREGROUND
     PROCESSLIST_ID: 1
   PROCESSLIST_USER: NULL
   PROCESSLIST_HOST: NULL
     PROCESSLIST_DB: NULL
PROCESSLIST_COMMAND: Daemon
   PROCESSLIST_TIME: 1509
  PROCESSLIST_STATE: Suspending
   PROCESSLIST_INFO: NULL
   PARENT_THREAD_ID: 1
               ROLE: NULL
       INSTRUMENTED: YES
            HISTORY: YES
    CONNECTION_TYPE: NULL
       THREAD_OS_ID: 18677
</pre><p>
        The <code class="literal">thread/sql/compress_gtid_table</code> thread
        normally sleeps until
        <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
        transactions have been executed, then wakes up to perform
        compression of the <code class="literal">mysql.gtid_executed</code> table
        as described previously. It then sleeps until another
        <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
        transactions have taken place, then wakes up to perform the
        compression again, repeating this loop indefinitely. Setting
        this value to 0 when binary logging is disabled means that the
        thread always sleeps and never wakes up.
      </p><p>
        When the server instance is started and the
        <code class="literal">thread/sql/compress_gtid_table</code> thread is
        launched, in most server configurations, compression is
        performed for the <code class="literal">mysql.gtid_executed</code> table.
        In releases before MySQL 8.0.17 when binary logging is enabled,
        compression is triggered by the fact of the binary log being
        rotated at startup. In releases from MySQL 8.0.20, compression
        is triggered by the thread launch. In the intervening releases,
        compression does not take place at startup.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-lifecycle"></a>17.1.3.2 GTID Life Cycle</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271573072"></a><p>
      The life cycle of a GTID consists of the following steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          A transaction is executed and committed on the master. This
          client transaction is assigned a GTID composed of the master's
          UUID and the smallest nonzero transaction sequence number not
          yet used on this server. The GTID is written to the master's
          binary log (immediately preceding the transaction itself in
          the log). If a client transaction is not written to the binary
          log (for example, because the transaction was filtered out, or
          the transaction was read-only), it is not assigned a GTID.
        </p></li><li class="listitem"><p>
          If a GTID was assigned for the transaction, the GTID is
          persisted atomically at commit time by writing it to the
          binary log at the beginning of the transaction (as a
          <code class="literal">Gtid_log_event</code>). Whenever the binary log is
          rotated or the server is shut down, the server writes GTIDs
          for all transactions that were written into the previous
          binary log file into the
          <code class="literal">mysql.gtid_executed</code> table.
        </p></li><li class="listitem"><p>
          If a GTID was assigned for the transaction, the GTID is
          externalized non-atomically (very shortly after the
          transaction is committed) by adding it to the set of GTIDs in
          the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system
          variable (<code class="literal">@@GLOBAL.gtid_executed</code>). This
          GTID set contains a representation of the set of all committed
          GTID transactions, and it is used in replication as a token
          that represents the server state. With binary logging enabled
          (as required for the master), the set of GTIDs in the
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
          is a complete record of the transactions applied, but the
          <code class="literal">mysql.gtid_executed</code> table is not, because
          the most recent history is still in the current binary log
          file.
        </p></li><li class="listitem"><p>
          After the binary log data is transmitted to the slave and
          stored in the slave's relay log (using established
          mechanisms for this process, see
          <a class="xref" href="replication.html#replication-implementation" title="17.2 Replication Implementation">Section 17.2, “Replication Implementation”</a>, for details),
          the slave reads the GTID and sets the value of its
          <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> system variable as
          this GTID. This tells the slave that the next transaction must
          be logged using this GTID. It is important to note that the
          slave sets <code class="literal">gtid_next</code> in a session context.
        </p></li><li class="listitem"><p>
          The slave verifies that no thread has yet taken ownership of
          the GTID in <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> in
          order to process the transaction. By reading and checking the
          replicated transaction's GTID first, before processing the
          transaction itself, the slave guarantees not only that no
          previous transaction having this GTID has been applied on the
          slave, but also that no other session has already read this
          GTID but has not yet committed the associated transaction. So
          if multiple clients attempt to apply the same transaction
          concurrently, the server resolves this by letting only one of
          them execute. The <a class="link" href="replication.html#sysvar_gtid_owned"><code class="literal">gtid_owned</code></a>
          system variable (<code class="literal">@@GLOBAL.gtid_owned</code>) for
          the slave shows each GTID that is currently in use and the ID
          of the thread that owns it. If the GTID has already been used,
          no error is raised, and the auto-skip function is used to
          ignore the transaction.
        </p></li><li class="listitem"><p>
          If the GTID has not been used, the slave applies the
          replicated transaction. Because
          <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> is set to the GTID
          already assigned by the master, the slave does not attempt to
          generate a new GTID for this transaction, but instead uses the
          GTID stored in <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>.
        </p></li><li class="listitem"><p>
          If binary logging is enabled on the slave, the GTID is
          persisted atomically at commit time by writing it to the
          binary log at the beginning of the transaction (as a
          <code class="literal">Gtid_log_event</code>). Whenever the binary log is
          rotated or the server is shut down, the server writes GTIDs
          for all transactions that were written into the previous
          binary log file into the
          <code class="literal">mysql.gtid_executed</code> table.
        </p></li><li class="listitem"><p>
          If binary logging is disabled on the slave, the GTID is
          persisted atomically by writing it directly into the
          <code class="literal">mysql.gtid_executed</code> table. MySQL appends a
          statement to the transaction to insert the GTID into the
          table. From MySQL 8.0, this operation is atomic for DDL
          statements as well as for DML statements. In this situation,
          the <code class="literal">mysql.gtid_executed</code> table is a complete
          record of the transactions applied on the slave.
        </p></li><li class="listitem"><p>
          Very shortly after the replicated transaction is committed on
          the slave, the GTID is externalized non-atomically by adding
          it to the set of GTIDs in the
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
          (<code class="literal">@@GLOBAL.gtid_executed</code>) for the slave. As
          for the master, this GTID set contains a representation of the
          set of all committed GTID transactions. If binary logging is
          disabled on the slave, the
          <code class="literal">mysql.gtid_executed</code> table is also a
          complete record of the transactions applied on the slave. If
          binary logging is enabled on the slave, meaning that some
          GTIDs are only recorded in the binary log, the set of GTIDs in
          the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system
          variable is the only complete record.
</p></li></ol>
</div>
<p>
      Client transactions that are completely filtered out on the master
      are not assigned a GTID, therefore they are not added to the set
      of transactions in the
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable, or
      added to the <code class="literal">mysql.gtid_executed</code> table.
      However, the GTIDs of replicated transactions that are completely
      filtered out on the slave are persisted. If binary logging is
      enabled on the slave, the filtered-out transaction is written to
      the binary log as a <code class="literal">Gtid_log_event</code> followed by
      an empty transaction containing only <code class="literal">BEGIN</code> and
      <code class="literal">COMMIT</code> statements. If binary logging is
      disabled, the GTID of the filtered-out transaction is written to
      the <code class="literal">mysql.gtid_executed</code> table. Preserving the
      GTIDs for filtered-out transactions ensures that the
      <code class="literal">mysql.gtid_executed</code> table and the set of GTIDs
      in the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system
      variable can be compressed. It also ensures that the filtered-out
      transactions are not retrieved again if the slave reconnects to
      the master, as explained in
      <a class="xref" href="replication.html#replication-gtids-auto-positioning" title="17.1.3.3 GTID Auto-Positioning">Section 17.1.3.3, “GTID Auto-Positioning”</a>.
    </p><p>
      On a multithreaded replication slave (with
      <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers &gt; 0</code></a> ),
      transactions can be applied in parallel, so replicated
      transactions can commit out of order (unless
      <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a> is
      set). When that happens, the set of GTIDs in the
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
      will contain multiple GTID ranges with gaps between them. (On a
      master or a single-threaded replication slave, there will be
      monotonically increasing GTIDs without gaps between the numbers.)
      Gaps on multithreaded replication slaves only occur among the most
      recently applied transactions, and are filled in as replication
      progresses. When replication threads are stopped cleanly using the
      <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> statement, ongoing
      transactions are applied so that the gaps are filled in. In the
      event of a shutdown such as a server failure or the use of the
      <a class="link" href="sql-statements.html#kill" title="13.7.8.4 KILL Statement"><code class="literal">KILL</code></a> statement to stop replication
      threads, the gaps might remain.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-gtids-assign"></a>What changes are assigned a GTID?</h5>
</div>
</div>
</div>
<p>
        The typical scenario is that the server generates a new GTID for
        a committed transaction. However, GTIDs can also be assigned to
        other changes besides transactions, and in some cases a single
        transaction can be assigned multiple GTIDs.
      </p><p>
        Every database change (DDL or DML) that is written to the binary
        log is assigned a GTID. This includes changes that are
        autocommitted, and changes that are committed using
        <code class="literal">BEGIN</code> and <code class="literal">COMMIT</code> or
        <code class="literal">START TRANSACTION</code> statements. A GTID is also
        assigned to the creation, alteration, or deletion of a database,
        and of a non-table database object such as a procedure,
        function, trigger, event, view, user, role, or grant.
      </p><p>
        Non-transactional updates as well as transactional updates are
        assigned GTIDs. In addition, for a non-transactional update, if
        a disk write failure occurs while attempting to write to the
        binary log cache and a gap is therefore created in the binary
        log, the resulting incident log event is assigned a GTID.
      </p><p>
        When a table is automatically dropped by a generated statement
        in the binary log, a GTID is assigned to the statement.
        Temporary tables are dropped automatically when a replication
        slave begins to apply events from a master that has just been
        started, and when statement-based replication is in use
        (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a>) and a
        user session that has open temporary tables disconnects. Tables
        that use the <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> storage engine
        are deleted automatically the first time they are accessed after
        the server is started, because rows might have been lost during
        the shutdown.
      </p><p>
        When a transaction is not written to the binary log on the
        server of origin, the server does not assign a GTID to it. This
        includes transactions that are rolled back and transactions that
        are executed while binary logging is disabled on the server of
        origin, either globally (with <code class="literal">--skip-log-bin</code>
        specified in the server's configuration) or for the session
        (<code class="literal">SET @@SESSION.sql_log_bin = 0</code>). This also
        includes no-op transactions when row-based replication is in use
        (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>).
      </p><p>
        XA transactions are assigned separate GTIDs for the <code class="literal">XA
        PREPARE</code> phase of the transaction and the <code class="literal">XA
        COMMIT</code> or <code class="literal">XA ROLLBACK</code> phase of the
        transaction. XA transactions are persistently prepared so that
        users can commit them or roll them back in the case of a failure
        (which in a replication topology might include a failover to
        another server). The two parts of the transaction are therefore
        replicated separately, so they must have their own GTIDs, even
        though a non-XA transaction that is rolled back would not have a
        GTID.
      </p><p>
        In the following special cases, a single statement can generate
        multiple transactions, and therefore be assigned multiple GTIDs:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A stored procedure is invoked that commits multiple
            transactions. One GTID is generated for each transaction
            that the procedure commits.
          </p></li><li class="listitem"><p>
            A multi-table <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TABLE</code></a>
            statement drops tables of different types. Multiple GTIDs
            can be generated if any of the tables use storage engines
            that do not support atomic DDL, or if any of the tables are
            temporary tables.
          </p></li><li class="listitem"><p>
            A
            <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
            TABLE ... SELECT</code></a> statement is issued when
            row-based replication is in use
            (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>). One
            GTID is generated for the <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
            TABLE</code></a> action and one GTID is generated for the
            row-insert actions.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-gtids-gtid-next"></a>The <code class="literal">gtid_next</code> System Variable</h5>

</div>

</div>

</div>
<p>
        By default, for new transactions committed in user sessions, the
        server automatically generates and assigns a new GTID. When the
        transaction is applied on a replication slave, the GTID from the
        server of origin is preserved. You can change this behavior by
        setting the session value of the
        <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> system variable:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            When <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> is set to
            <code class="literal">AUTOMATIC</code>, which is the default, and a
            transaction is committed and written to the binary log, the
            server automatically generates and assigns a new GTID. If a
            transaction is rolled back or not written to the binary log
            for another reason, the server does not generate and assign
            a GTID.
          </p></li><li class="listitem"><p>
            If you set <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> to a
            valid GTID (consisting of a UUID and a transaction sequence
            number, separated by a colon), the server assigns that GTID
            to your transaction. This GTID is assigned and added to
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> even when the
            transaction is not written to the binary log, or when the
            transaction is empty.
</p></li></ul>
</div>
<p>
        Note that after you set
        <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> to a specific GTID,
        and the transaction has been committed or rolled back, an
        explicit <code class="literal">SET @@SESSION.gtid_next</code> statement
        must be issued before any other statement. You can use this to
        set the GTID value back to <code class="literal">AUTOMATIC</code> if you
        do not want to assign any more GTIDs explicitly.
      </p><p>
        When replication applier threads apply replicated transactions,
        they use this technique, setting
        <code class="literal">@@SESSION.gtid_next</code> explicitly to the GTID of
        the replicated transaction as assigned on the server of origin.
        This means the GTID from the server of origin is retained,
        rather than a new GTID being generated and assigned by the
        replication slave. It also means the GTID is added to
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> on the
        replication slave even when binary logging or slave update
        logging is disabled on the slave, or when the transaction is a
        no-op or is filtered out on the slave.
      </p><p>
        It is possible for a client to simulate a replicated transaction
        by setting <code class="literal">@@SESSION.gtid_next</code> to a specific
        GTID before executing the transaction. This technique is used by
        <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> to generate a dump of the binary
        log that the client can replay to preserve GTIDs. A simulated
        replicated transaction committed through a client is completely
        equivalent to a replicated transaction committed through a
        replication applier thread, and they cannot be distinguished
        after the fact.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-gtids-gtid-purged"></a>The <code class="literal">gtid_purged</code> System Variable</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271474720"></a><a class="indexterm" name="idm46444271473232"></a><p>
        The set of GTIDs in the
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system variable
        (<code class="literal">@@GLOBAL.gtid_purged</code>) contains the GTIDs of
        all the transactions that have been committed on the server, but
        do not exist in any binary log file on the server.
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> is a subset of
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. The following
        categories of GTIDs are in
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            GTIDs of replicated transactions that were committed with
            binary logging disabled on the slave.
          </p></li><li class="listitem"><p>
            GTIDs of transactions that were written to a binary log file
            that has now been purged.
          </p></li><li class="listitem"><p>
            GTIDs that were added explicitly to the set by the statement
            <code class="literal">SET @@GLOBAL.gtid_purged</code>.
</p></li></ul>
</div>
<p>
        You can change the value of
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> in order to record
        on the server that the transactions in a certain GTID set have
        been applied, although they do not exist in any binary log on
        the server. When you add GTIDs to
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>, they are also
        added to <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. An
        example use case for this action is when you are restoring a
        backup of one or more databases on a server, but you do not have
        the relevant binary logs containing the transactions on the
        server. Before MySQL 8.0, you could only change the value of
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> when
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> (and therefore
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>) was empty. From
        MySQL 8.0, this restriction does not apply, and you can also
        choose whether to replace the whole GTID set in
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> with a specified
        GTID set, or to add a specified GTID set to the GTIDs already in
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>. For details of how
        to do this, see the description for
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>.
      </p><p>
        The sets of GTIDs in the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system variables
        are initialized when the server starts. Every binary log file
        begins with the event
        <code class="literal">Previous_gtids_log_event</code>, which contains the
        set of GTIDs in all previous binary log files (composed from the
        GTIDs in the preceding file's
        <code class="literal">Previous_gtids_log_event</code>, and the GTIDs of
        every <code class="literal">Gtid_log_event</code> in the preceding file
        itself). The contents of
        <code class="literal">Previous_gtids_log_event</code> in the oldest and
        most recent binary log files are used to compute the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> sets at server
        startup:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> is computed
            as the union of the GTIDs in
            <code class="literal">Previous_gtids_log_event</code> in the most
            recent binary log file, the GTIDs of transactions in that
            binary log file, and the GTIDs stored in the
            <code class="literal">mysql.gtid_executed</code> table. This GTID set
            contains all the GTIDs that have been used (or added
            explicitly to <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>)
            on the server, whether or not they are currently in a binary
            log file on the server. It does not include the GTIDs for
            transactions that are currently being processed on the
            server (<code class="literal">@@GLOBAL.gtid_owned</code>).
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> is computed by
            first adding the GTIDs in
            <code class="literal">Previous_gtids_log_event</code> in the most
            recent binary log file and the GTIDs of transactions in that
            binary log file. This step gives the set of GTIDs that are
            currently, or were once, recorded in a binary log on the
            server (<code class="literal">gtids_in_binlog</code>). Next, the GTIDs
            in <code class="literal">Previous_gtids_log_event</code> in the oldest
            binary log file are subtracted from
            <code class="literal">gtids_in_binlog</code>. This step gives the set
            of GTIDs that are currently recorded in a binary log on the
            server (<code class="literal">gtids_in_binlog_not_purged</code>).
            Finally, <code class="literal">gtids_in_binlog_not_purged</code> is
            subtracted from
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. The result
            is the set of GTIDs that have been used on the server, but
            are not currently recorded in a binary log file on the
            server, and this result is used to initialize
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>.
</p></li></ul>
</div>
<p>
        If binary logs from MySQL 5.7.7 or older are involved in these
        computations, it is possible for incorrect GTID sets to be
        computed for <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>, and they remain
        incorrect even if the server is later restarted. For details,
        see the description for the
        <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery</code></a>
        system variable, which controls how the binary logs are iterated
        to compute the GTID sets. If one of the situations described
        there applies on a server, set
        <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>
        in the server's configuration file before starting it. That
        setting makes the server iterate all the binary log files (not
        just the newest and oldest) to find where GTID events start to
        appear. This process could take a long time if the server has a
        large number of binary log files without GTID events.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-gtids-execution-history"></a>Resetting the GTID Execution History</h5>

</div>

</div>

</div>
<p>
        If you need to reset the GTID execution history on a server, use
        the <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> statement. For
        example, you might need to do this after carrying out test
        queries to verify a replication setup on new GTID-enabled
        servers, or when you want to join a new server to a replication
        group but it contains some unwanted local transactions that are
        not accepted by Group Replication.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          Use <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> with caution
          to avoid losing any wanted GTID execution history and binary
          log files.
</p>
</div>
<p>
        Before issuing <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a>,
        ensure that you have backups of the server's binary log files
        and binary log index file, if any, and obtain and save the GTID
        set held in the global value of the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
        (for example, by issuing a <code class="literal">SELECT
        @@GLOBAL.gtid_executed</code> statement and saving the
        results). If you are removing unwanted transactions from that
        GTID set, use <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> to examine the
        contents of the transactions to ensure that they have no value,
        contain no data that must be saved or replicated, and did not
        result in data changes on the server.
      </p><p>
        When you issue <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a>, the
        following reset operations are carried out:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The value of the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system variable
            is set to an empty string (<code class="literal">''</code>).
          </p></li><li class="listitem"><p>
            The global value (but not the session value) of the
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system
            variable is set to an empty string.
          </p></li><li class="listitem"><p>
            The <code class="literal">mysql.gtid_executed</code> table is cleared
            (see
            <a class="xref" href="replication.html#replication-gtids-gtid-executed-table" title="mysql.gtid_executed Table">mysql.gtid_executed Table</a>).
          </p></li><li class="listitem"><p>
            If the server has binary logging enabled, the existing
            binary log files are deleted and the binary log index file
            is cleared.
</p></li></ul>
</div>
<p>
        Note that <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> is the
        method to reset the GTID execution history even if the server is
        a replication slave where binary logging is disabled.
        <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> has no effect on the
        GTID execution history.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-auto-positioning"></a>17.1.3.3 GTID Auto-Positioning</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271393520"></a><p>
      GTIDs replace the file-offset pairs previously required to
      determine points for starting, stopping, or resuming the flow of
      data between master and slave. When GTIDs are in use, all the
      information that the slave needs for synchronizing with the master
      is obtained directly from the replication data stream.
    </p><p>
      To start a slave using GTID-based replication, you do not include
      <code class="literal">MASTER_LOG_FILE</code> or
      <code class="literal">MASTER_LOG_POS</code> options in the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement used to
      direct the slave to replicate from a given master. These options
      specify the name of the log file and the starting position within
      the file, but with GTIDs the slave does not need this nonlocal
      data. Instead, you need to enable the
      <code class="literal">MASTER_AUTO_POSITION</code> option. For full
      instructions to configure and start masters and slaves using
      GTID-based replication, see
      <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a>.
    </p><p>
      The <code class="literal">MASTER_AUTO_POSITION</code> option is disabled by
      default. If multi-source replication is enabled on the slave, you
      need to set the option for each applicable replication channel.
      Disabling the <code class="literal">MASTER_AUTO_POSITION</code> option again
      makes the slave revert to file-based replication, in which case
      you must also specify one or both of the
      <code class="literal">MASTER_LOG_FILE</code> or
      <code class="literal">MASTER_LOG_POS</code> options.
    </p><p>
      When a replication slave has GTIDs enabled
      (<a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">GTID_MODE=ON</code></a>,
      <code class="literal">ON_PERMISSIVE,</code> or
      <code class="literal">OFF_PERMISSIVE</code> ) and the
      <code class="literal">MASTER_AUTO_POSITION</code> option enabled,
      auto-positioning is activated for connection to the master. The
      master must have <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">GTID_MODE=ON</code></a> set
      in order for the connection to succeed. In the initial handshake,
      the slave sends a GTID set containing the transactions that it has
      already received, committed, or both. This GTID set is equal to
      the union of the set of GTIDs in the
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> system variable
      (<code class="literal">@@GLOBAL.gtid_executed</code>), and the set of GTIDs
      recorded in the Performance Schema
      <a class="link" href="performance-schema.html#replication-connection-status-table" title="26.12.11.2 The replication_connection_status Table"><code class="literal">replication_connection_status</code></a> table
      as received transactions (the result of the statement
      <code class="literal">SELECT RECEIVED_TRANSACTION_SET FROM
      PERFORMANCE_SCHEMA.replication_connection_status</code>).
    </p><p>
      The master responds by sending all transactions recorded in its
      binary log whose GTID is not included in the GTID set sent by the
      slave. This exchange ensures that the master only sends the
      transactions with a GTID that the slave has not already received
      or committed. If the slave receives transactions from more than
      one master, as in the case of a diamond topology, the auto-skip
      function ensures that the transactions are not applied twice.
    </p><p>
      If any of the transactions that should be sent by the master have
      been purged from the master's binary log, or added to the set of
      GTIDs in the <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system
      variable by another method, the master sends the error
      <span class="errorname">ER_MASTER_HAS_PURGED_REQUIRED_GTIDS</span> to the
      slave, and replication does not start. The GTIDs of the missing
      purged transactions are identified and listed in the master's
      error log in the warning message
      <span class="errorname">ER_FOUND_MISSING_GTIDS</span>. The slave cannot
      recover automatically from this error because parts of the
      transaction history that are needed to catch up with the master
      have been purged. Attempting to reconnect without the
      <code class="literal">MASTER_AUTO_POSITION</code> option enabled only
      results in the loss of the purged transactions on the slave. The
      correct approach to recover from this situation is for the slave
      to replicate the missing transactions listed in the
      <span class="errorname">ER_FOUND_MISSING_GTIDS</span> message from another
      source, or for the slave to be replaced by a new slave created
      from a more recent backup. Consider revising the binary log
      expiration period
      (<a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>) on
      the master to ensure that the situation does not occur again.
    </p><p>
      If during the exchange of transactions it is found that the slave
      has received or committed transactions with the master's UUID in
      the GTID, but the master itself does not have a record of them,
      the master sends the error
      <span class="errorname">ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER</span> to the
      slave and replication does not start. This situation can occur if
      a master that does not have
      <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a> set experiences a
      power failure or operating system crash, and loses committed
      transactions that have not yet been synchronized to the binary log
      file, but have been received by the slave. The master and slave
      can diverge if any clients commit transactions on the master after
      it is restarted, which can lead to the situation where the master
      and slave are using the same GTID for different transactions. The
      correct approach to recover from this situation is to check
      manually whether the master and slave have diverged. If the same
      GTID is now in use for different transactions, you either need to
      perform manual conflict resolution for individual transactions as
      required, or remove either the master or the slave from the
      replication topology. If the issue is only missing transactions on
      the master, you can make the master into a slave instead, allow it
      to catch up with the other servers in the replication topology,
      and then make it a master again if needed.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-howto"></a>17.1.3.4 Setting Up Replication Using GTIDs</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271361488"></a><p>
      This section describes a process for configuring and starting
      GTID-based replication in MySQL 8.0. This is a
      <span class="quote">“<span class="quote">cold start</span>”</span> procedure that assumes either that you
      are starting the replication master for the first time, or that it
      is possible to stop it; for information about provisioning
      replication slaves using GTIDs from a running master, see
      <a class="xref" href="replication.html#replication-gtids-failover" title="17.1.3.5 Using GTIDs for Failover and Scaleout">Section 17.1.3.5, “Using GTIDs for Failover and Scaleout”</a>. For information
      about changing GTID mode on servers online, see
      <a class="xref" href="replication.html#replication-mode-change-online" title="17.1.5 Changing Replication Modes on Online Servers">Section 17.1.5, “Changing Replication Modes on Online Servers”</a>.
    </p><p>
      The key steps in this startup process for the simplest possible
      GTID replication topology, consisting of one master and one slave,
      are as follows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          If replication is already running, synchronize both servers by
          making them read-only.
        </p></li><li class="listitem"><p>
          Stop both servers.
        </p></li><li class="listitem"><p>
          Restart both servers with GTIDs enabled and the correct
          options configured.
        </p><p>
          The <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> options necessary to start the
          servers as described are discussed in the example that follows
          later in this section.
        </p></li><li class="listitem"><p>
          Instruct the slave to use the master as the replication data
          source and to use auto-positioning. The SQL statements needed
          to accomplish this step are described in the example that
          follows later in this section.
        </p></li><li class="listitem"><p>
          Take a new backup. Binary logs containing transactions without
          GTIDs cannot be used on servers where GTIDs are enabled, so
          backups taken before this point cannot be used with your new
          configuration.
        </p></li><li class="listitem"><p>
          Start the slave, then disable read-only mode on both servers,
          so that they can accept updates.
</p></li></ol>
</div>
<p>
      In the following example, two servers are already running as
      master and slave, using MySQL's binary log position-based
      replication protocol. If you are starting with new servers, see
      <a class="xref" href="replication.html#replication-howto-repuser" title="17.1.2.3 Creating a User for Replication">Section 17.1.2.3, “Creating a User for Replication”</a> for information about
      adding a specific user for replication connections and
      <a class="xref" href="replication.html#replication-howto-masterbaseconfig" title="17.1.2.1 Setting the Replication Master Configuration">Section 17.1.2.1, “Setting the Replication Master Configuration”</a> for
      information about setting the
      <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> variable. The following
      examples show how to store <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> startup
      options in server's option file, see
      <a class="xref" href="programs.html#option-files" title="4.2.2.2 Using Option Files">Section 4.2.2.2, “Using Option Files”</a> for more information. Alternatively
      you can use startup options when running
      <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>.
    </p><p>
      Most of the steps that follow require the use of the MySQL
      <code class="literal">root</code> account or another MySQL user account that
      has the <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a> privilege.
      <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a> <code class="literal">shutdown</code> requires
      either the <code class="literal">SUPER</code> privilege or the
      <a class="link" href="security.html#priv_shutdown"><code class="literal">SHUTDOWN</code></a> privilege.
    </p><p><b>Step 1: Synchronize the servers. </b>
        This step is only required when working with servers which are
        already replicating without using GTIDs. For new servers proceed
        to Step 3. Make the servers read-only by setting the
        <a class="link" href="server-administration.html#sysvar_read_only"><code class="literal">read_only</code></a> system variable to
        <code class="literal">ON</code> on each server by issuing the following:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET @@GLOBAL.read_only = ON;</code></strong>
</pre><p>
      Wait for all ongoing transactions to commit or roll back. Then,
      allow the slave to catch up with the master. <span class="emphasis"><em>It is
      extremely important that you make sure the slave has processed all
      updates before continuing</em></span>.

      
    </p><p>
      If you use binary logs for anything other than replication, for
      example to do point in time backup and restore, wait until you do
      not need the old binary logs containing transactions without
      GTIDs. Ideally, wait for the server to purge all binary logs, and
      wait for any existing backup to expire.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        It is important to understand that logs containing transactions
        without GTIDs cannot be used on servers where GTIDs are enabled.
        Before proceeding, you must be sure that transactions without
        GTIDs do not exist anywhere in the topology.
</p>
</div>
<p><b>Step 2: Stop both servers. </b>
        Stop each server using <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a> as shown
        here, where <em class="replaceable"><code>username</code></em> is the user name
        for a MySQL user having sufficient privileges to shut down the
        server:
      </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin -u<em class="replaceable"><code>username</code></em> -p shutdown</code></strong>
</pre><p>
      Then supply this user's password at the prompt.
    </p><p><b>Step 3: Start both servers with GTIDs enabled. </b>
        To enable GTID-based replication, each server must be started
        with GTID mode enabled by setting the
        <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> variable to
        <code class="literal">ON</code>, and with the
        <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a>
        variable enabled to ensure that only statements which are safe
        for GTID-based replication are logged. For example:
      </p><pre data-lang="ini" class="programlisting">gtid_mode=ON
enforce-gtid-consistency=ON</pre><p>
      In addition, you should start slaves with the
      <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option before
      configuring the slave settings. For more information on GTID
      related options and variables, see
      <a class="xref" href="replication.html#replication-options-gtids" title="17.1.6.5 Global Transaction ID System Variables">Section 17.1.6.5, “Global Transaction ID System Variables”</a>.
    </p><p>
      It is not mandatory to have binary logging enabled in order to use
      GTIDs when using the
      <a class="xref" href="replication.html#replication-gtids-gtid-executed-table" title="mysql.gtid_executed Table">mysql.gtid_executed Table</a>. Masters
      must always have binary logging enabled in order to be able to
      replicate. However, slave servers can use GTIDs but without binary
      logging. If you need to disable binary logging on a slave server,
      you can do this by specifying the
      <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
      and <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> options
      for the slave.
    </p><p><b>Step 4: Configure the slave to use GTID-based auto-positioning. </b>
        Tell the slave to use the master with GTID based transactions as
        the replication data source, and to use GTID-based
        auto-positioning rather than file-based positioning. Issue a
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement on the
        slave, including the <code class="literal">MASTER_AUTO_POSITION</code>
        option in the statement to tell the slave that the master's
        transactions are identified by GTIDs.
      </p><p>
      You may also need to supply appropriate values for the
      master's host name and port number as well as the user name
      and password for a replication user account which can be used by
      the slave to connect to the master; if these have already been set
      prior to Step 1 and no further changes need to be made, the
      corresponding options can safely be omitted from the statement
      shown here.
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO</code></strong>
     &gt;     <strong class="userinput"><code>MASTER_HOST = <em class="replaceable"><code>host</code></em>,</code></strong>
     &gt;     <strong class="userinput"><code>MASTER_PORT = <em class="replaceable"><code>port</code></em>,</code></strong>
     &gt;     <strong class="userinput"><code>MASTER_USER = <em class="replaceable"><code>user</code></em>,</code></strong>
     &gt;     <strong class="userinput"><code>MASTER_PASSWORD = <em class="replaceable"><code>password</code></em>,</code></strong>
     &gt;     <strong class="userinput"><code>MASTER_AUTO_POSITION = 1;</code></strong>
</pre><p>
      Neither the <code class="literal">MASTER_LOG_FILE</code> option nor the
      <code class="literal">MASTER_LOG_POS</code> option may be used with
      <code class="literal">MASTER_AUTO_POSITION</code> set equal to 1. Attempting
      to do so causes the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement to fail with an error.
    </p><p><b>Step 5: Take a new backup. </b>
        Existing backups that were made before you enabled GTIDs can no
        longer be used on these servers now that you have enabled GTIDs.
        Take a new backup at this point, so that you are not left
        without a usable backup.
      </p><p>
      For instance, you can execute <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH
      LOGS</code></a> on the server where you are taking backups. Then
      either explicitly take a backup or wait for the next iteration of
      any periodic backup routine you may have set up.
    </p><p><b>Step 6: Start the slave and disable read-only mode. </b>
        Start the slave like this:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre><p>
      The following step is only necessary if you configured a server to
      be read-only in Step 1. To allow the server to begin accepting
      updates again, issue the following statement:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET @@GLOBAL.read_only = OFF;</code></strong>
</pre><p>
      GTID-based replication should now be running, and you can begin
      (or resume) activity on the master as before.
      <a class="xref" href="replication.html#replication-gtids-failover" title="17.1.3.5 Using GTIDs for Failover and Scaleout">Section 17.1.3.5, “Using GTIDs for Failover and Scaleout”</a>, discusses creation
      of new slaves when using GTIDs.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-failover"></a>17.1.3.5 Using GTIDs for Failover and Scaleout</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271283040"></a><a class="indexterm" name="idm46444271281552"></a><p>
      There are a number of techniques when using MySQL Replication with
      Global Transaction Identifiers (GTIDs) for provisioning a new
      slave which can then be used for scaleout, being promoted to
      master as necessary for failover. This section describes the
      following techniques:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="xref" href="replication.html#replication-gtids-failover-replicate" title="Simple replication">Simple replication</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="replication.html#replication-gtids-failover-copy" title="Copying data and transactions to the slave">Copying data and transactions to the slave</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="replication.html#replication-gtids-failover-empty" title="Injecting empty transactions">Injecting empty transactions</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="replication.html#replication-gtids-failover-gtid-purged" title="Excluding transactions with gtid_purged">Excluding transactions with gtid_purged</a>
        </p></li><li class="listitem"><p>
          <a class="xref" href="replication.html#replication-gtids-restoring-mysqlbinlog" title="Restoring GTID mode slaves">Restoring GTID mode slaves</a>
</p></li></ul>
</div>
<p>
      Global transaction identifiers were added to MySQL Replication for
      the purpose of simplifying in general management of the
      replication data flow and of failover activities in particular.
      Each identifier uniquely identifies a set of binary log events
      that together make up a transaction. GTIDs play a key role in
      applying changes to the database: the server automatically skips
      any transaction having an identifier which the server recognizes
      as one that it has processed before. This behavior is critical for
      automatic replication positioning and correct failover.
    </p><p>
      The mapping between identifiers and sets of events comprising a
      given transaction is captured in the binary log. This poses some
      challenges when provisioning a new server with data from another
      existing server. To reproduce the identifier set on the new
      server, it is necessary to copy the identifiers from the old
      server to the new one, and to preserve the relationship between
      the identifiers and the actual events. This is neccessary for
      restoring a slave that is immediately available as a candidate to
      become a new master on failover or switchover.
    </p><p><a name="replication-gtids-failover-replicate"></a><b>Simple replication. </b>
        The easiest way to reproduce all identifiers and transactions on
        a new server is to make the new server into the slave of a
        master that has the entire execution history, and enable global
        transaction identifiers on both servers. See
        <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a>, for more information.
      </p><p>
      Once replication is started, the new server copies the entire
      binary log from the master and thus obtains all information about
      all GTIDs.
    </p><p>
      This method is simple and effective, but requires the slave to
      read the binary log from the master; it can sometimes take a
      comparatively long time for the new slave to catch up with the
      master, so this method is not suitable for fast failover or
      restoring from backup. This section explains how to avoid fetching
      all of the execution history from the master by copying binary log
      files to the new server.
    </p><p><a name="replication-gtids-failover-copy"></a><b>Copying data and transactions to the slave. </b>
        Executing the entire transaction history can be time-consuming
        when the source server has processed a large number of
        transactions previously, and this can represent a major
        bottleneck when setting up a new replication slave. To eliminate
        this requirement, a snapshot of the data set, the binary logs
        and the global transaction information the source server
        contains can be imported to the new slave. The source server can
        be either the master or the slave, but you must ensure that the
        source has processed all required transactions before copying
        the data.
      </p><p>
      There are several variants of this method, the difference being in
      the manner in which data dumps and transactions from binary logs
      are transfered to the slave, as outlined here:
</p>
<div class="variablelist">
<dl class="variablelist"><dt><span class="term">
          Data Set
</span></dt><dd>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
                Create a dump file using <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> on
                the source server. Set the <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>
                option <a class="link" href="programs.html#option_mysqldump_master-data"><code class="option">--master-data</code></a>
                (with the default value of 1) to include a
                <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
                statement with binary logging information. Set the
                <a class="link" href="programs.html#option_mysqldump_set-gtid-purged"><code class="option">--set-gtid-purged</code></a>
                option to <code class="literal">AUTO</code> (the default) or
                <code class="literal">ON</code>, to include information about
                executed transactions in the dump. Then use the
                <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to import the dump file
                on the target server.
              </p></li><li class="listitem"><p>
                Alternatively, create a data snapshot of the source
                server using raw data files, then copy these files to
                the target server, following the instructions in
                <a class="xref" href="replication.html#replication-snapshot-method" title="17.1.2.5 Choosing a Method for Data Snapshots">Section 17.1.2.5, “Choosing a Method for Data Snapshots”</a>. If you
                use <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> tables, you can
                use the <span class="command"><strong>mysqlbackup</strong></span> command from the
                MySQL Enterprise Backup component to produce a
                consistent snapshot. This command records the log name
                and offset corresponding to the snapshot to be used on
                the slave. MySQL Enterprise Backup is a commercial
                product that is included as part of a MySQL Enterprise
                subscription. See
                <a class="xref" href="mysql-enterprise.html#mysql-enterprise-backup" title="30.2 MySQL Enterprise Backup Overview">Section 30.2, “MySQL Enterprise Backup Overview”</a> for detailed
                information.
              </p></li><li class="listitem"><p>
                Alternatively, stop both the source and target servers,
                copy the contents of the source's data directory to the
                new slave's data directory, then restart the slave.
                If you use this method, the slave must be configured for
                GTID-based replication, in other words with
                <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>. For
                instructions and important information for this method,
                see
                <a class="xref" href="replication.html#replication-howto-additionalslaves" title="17.1.2.8 Adding Slaves to a Replication Environment">Section 17.1.2.8, “Adding Slaves to a Replication Environment”</a>.
</p></li></ol>
</div>
</dd><dt><span class="term">
          Transaction History
        </span></dt><dd><p>
            If the source server has a complete transaction history in
            its binary logs (that is, the GTID set
            <code class="literal">@@GLOBAL.gtid_purged</code> is empty), you can
            use these methods.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
                Import the binary logs from the source server to the new
                slave using <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, with the
                <a class="link" href="programs.html#option_mysqlbinlog_read-from-remote-server"><code class="option">--read-from-remote-server</code></a>
                and
                <a class="link" href="programs.html#option_mysqlbinlog_read-from-remote-master"><code class="option">--read-from-remote-master</code></a>
                options.
              </p></li><li class="listitem"><p>
                Alternatively, copy the source server's binary log files
                to the slave. You can make copies from the slave using
                <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> with the
                <a class="link" href="programs.html#option_mysqlbinlog_read-from-remote-server"><code class="option">--read-from-remote-server</code></a>
                and <a class="link" href="programs.html#option_mysqlbinlog_raw"><code class="option">--raw</code></a> options.
                These can be read into the slave by using
                <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> <code class="literal">&gt;</code>
                <code class="filename"><em class="replaceable"><code>file</code></em></code>
                (without the <a class="link" href="programs.html#option_mysqlbinlog_raw"><code class="option">--raw</code></a>
                option) to export the binary log files to SQL files,
                then passing these files to the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>
                client for processing. Ensure that all of the binary log
                files are processed using a single
                <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> process, rather than multiple
                connections. For example:
              </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqlbinlog copied-binlog.000001 copied-binlog.000002 | mysql -u root -p</code></strong>
</pre><p>
                For more information, see
                <a class="xref" href="programs.html#mysqlbinlog-backup" title="4.6.8.3 Using mysqlbinlog to Back Up Binary Log Files">Section 4.6.8.3, “Using mysqlbinlog to Back Up Binary Log Files”</a>.
</p></li></ol>
</div>
</dd></dl>
</div>
<p>
      This method has the advantage that a new server is available
      almost immediately; only those transactions that were committed
      while the snapshot or dump file was being replayed still need to
      be obtained from the existing master. This means that the
      slave's availability is not instantanteous, but only a
      relatively short amount of time should be required for the slave
      to catch up with these few remaining transactions.
    </p><p>
      Copying over binary logs to the target server in advance is
      usually faster than reading the entire transaction execution
      history from the master in real time. However, it may not always
      be feasible to move these files to the target when required, due
      to size or other considerations. The two remaining methods for
      provisioning a new slave discussed in this section use other means
      to transfer information about transactions to the new slave.
    </p><p><a name="replication-gtids-failover-empty"></a><b>Injecting empty transactions. </b>
        The master's global
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> variable contains
        the set of all transactions executed on the master. Rather than
        copy the binary logs when taking a snapshot to provision a new
        server, you can instead note the content of
        <code class="literal">gtid_executed</code> on the server from which the
        snapshot was taken. Before adding the new server to the
        replication chain, simply commit an empty transaction on the new
        server for each transaction identifier contained in the
        master's <code class="literal">gtid_executed</code>, like this:
      </p><pre data-lang="sql" class="programlisting">SET GTID_NEXT='aaa-bbb-ccc-ddd:N';

BEGIN;
COMMIT;

SET GTID_NEXT='AUTOMATIC';</pre><p>
      Once all transaction identifiers have been reinstated in this way
      using empty transactions, you must flush and purge the
      slave's binary logs, as shown here, where
      <em class="replaceable"><code>N</code></em> is the nonzero suffix of the current
      binary log file name:
    </p><pre data-lang="sql" class="programlisting">FLUSH LOGS;
PURGE BINARY LOGS TO 'master-bin.00000<em class="replaceable"><code>N</code></em>';
</pre><p>
      You should do this to prevent this server from flooding the
      replication stream with false transactions in the event that it is
      later promoted to master. (The <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH
      LOGS</code></a> statement forces the creation of a new binary log
      file; <a class="link" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement"><code class="literal">PURGE BINARY LOGS</code></a> purges the
      empty transactions, but retains their identifiers.)
    </p><p>
      This method creates a server that is essentially a snapshot, but
      in time is able to become a master as its binary log history
      converges with that of the replication stream (that is, as it
      catches up with the master or masters). This outcome is similar in
      effect to that obtained using the remaining provisioning method,
      which we discuss in the next few paragraphs.
    </p><p><a name="replication-gtids-failover-gtid-purged"></a><b>Excluding transactions with gtid_purged. </b>
        The master's global
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> variable contains
        the set of all transactions that have been purged from the
        master's binary log. As with the method discussed
        previously (see
        <a class="xref" href="replication.html#replication-gtids-failover-empty" title="Injecting empty transactions">Injecting empty transactions</a>), you can
        record the value of
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> on the server
        from which the snapshot was taken (in place of copying the
        binary logs to the new server). Unlike the previous method,
        there is no need to commit empty transactions (or to issue
        <a class="link" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement"><code class="literal">PURGE BINARY LOGS</code></a>); instead, you
        can set <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> on the
        slave directly, based on the value of
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> on the server
        from which the backup or snapshot was taken.
      </p><p>
      As with the method using empty transactions, this method creates a
      server that is functionally a snapshot, but in time is able to
      become a master as its binary log history converges with that of
      the replication master or group.
    </p><p><a name="replication-gtids-restoring-mysqlbinlog"></a><b>Restoring GTID mode slaves. </b>
        When restoring a slave in a GTID based replication setup that
        has encountered an error, injecting an empty transaction may not
        solve the problem because an event does not have a GTID.
      </p><p>
      Use <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> to find the next transaction,
      which is probably the first transaction in the next log file after
      the event. Copy everything up to the <code class="literal">COMMIT</code> for
      that transaction, being sure to include the <code class="literal">SET
      @@SESSION.gtid_next</code>. Even if you are not using row-based
      replication, you can still run binary log row events in the
      command line client.
    </p><p>
      Stop the slave and run the transaction you copied. The
      <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output sets the delimiter to
      <code class="literal">/*!*/;</code>, so set it back:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>DELIMITER ;</code></strong>
</pre><p>
      Restart replication from the correct position automatically:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET GTID_NEXT=automatic;</code></strong>
mysql&gt; <strong class="userinput"><code>RESET SLAVE;</code></strong>
mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-restrictions"></a>17.1.3.6 Restrictions on Replication with GTIDs</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444271181424"></a><p>
      Because GTID-based replication is dependent on transactions, some
      features otherwise available in MySQL are not supported when using
      it. This section provides information about restrictions on and
      limitations of replication with GTIDs.
    </p><p><b>Updates involving nontransactional storage engines. </b>
        When using GTIDs, updates to tables using nontransactional
        storage engines such as <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a>
        cannot be made in the same statement or transaction as updates
        to tables using transactional storage engines such as
        <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>.
      </p><p>
      This restriction is due to the fact that updates to tables that
      use a nontransactional storage engine mixed with updates to tables
      that use a transactional storage engine within the same
      transaction can result in multiple GTIDs being assigned to the
      same transaction.
    </p><p>
      Such problems can also occur when the master and the slave use
      different storage engines for their respective versions of the
      same table, where one storage engine is transactional and the
      other is not. Also be aware that triggers that are defined to
      operate on nontransactional tables can be the cause of these
      problems.
    </p><p>
      In any of the cases just mentioned, the one-to-one correspondence
      between transactions and GTIDs is broken, with the result that
      GTID-based replication cannot function correctly.
    </p><p><b>CREATE TABLE ... SELECT statements. </b>
        <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
        TABLE ... SELECT</code></a> statements are not allowed when using
        GTID-based replication. When
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
        STATEMENT, a <code class="literal">CREATE TABLE ... SELECT</code>
        statement is recorded in the binary log as one transaction with
        one GTID, but if ROW format is used, the statement is recorded
        as two transactions with two GTIDs. If a master used STATEMENT
        format and a slave used ROW format, the slave would be unable to
        handle the transaction correctly, therefore the <code class="literal">CREATE
        TABLE ... SELECT</code> statement is disallowed with GTIDs to
        prevent this scenario.
      </p><p><b>Temporary tables. </b>
        When <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
        <code class="literal">STATEMENT</code>,
        <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TEMPORARY
        TABLE</code></a> and
        <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TEMPORARY
        TABLE</code></a> statements cannot be used inside transactions,
        procedures, functions, and triggers when GTIDs are in use on the
        server (that is, when the
        <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a> system
        variable is set to <code class="literal">ON</code>). They can be used
        outside these contexts when GTIDs are in use, provided that
        <a class="link" href="server-administration.html#sysvar_autocommit"><code class="literal">autocommit=1</code></a> is set. From MySQL
        8.0.13, when <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is
        set to <code class="literal">ROW</code> or <code class="literal">MIXED</code>,
        <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TEMPORARY
        TABLE</code></a> and
        <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TEMPORARY
        TABLE</code></a> statements are allowed inside a transaction,
        procedure, function, or trigger when GTIDs are in use. The
        statements are not written to the binary log and are therefore
        not replicated to slaves. The use of row-based replication means
        that the slaves remain in sync without the need to replicate
        temporary tables. If the removal of these statements from a
        transaction results in an empty transaction, the transaction is
        not written to the binary log.

      </p><p><b>Preventing execution of unsupported statements. </b>
        To prevent execution of statements that would cause GTID-based
        replication to fail, all servers must be started with the
        <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="option">--enforce-gtid-consistency</code></a> option
        when enabling GTIDs. This causes statements of any of the types
        discussed previously in this section to fail with an error.
      </p><p>
      Note that
      <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="option">--enforce-gtid-consistency</code></a> only
      takes effect if binary logging takes place for a statement. If
      binary logging is disabled on the server, or if statements are not
      written to the binary log because they are removed by a filter,
      GTID consistency is not checked or enforced for the statements
      that are not logged.
    </p><p>
      For information about other required startup options when enabling
      GTIDs, see <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a>.
    </p><p><b>Skipping transactions. </b>
        <a class="link" href="replication.html#sysvar_sql_slave_skip_counter"><code class="literal">sql_slave_skip_counter</code></a> is not
        supported when using GTIDs. If you need to skip transactions,
        use the value of the master's
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> variable instead;
        see <a class="xref" href="replication.html#replication-gtids-failover-empty" title="Injecting empty transactions">Injecting empty transactions</a>, for more
        information.
      </p><p><b>Ignoring servers. </b>
        The IGNORE_SERVER_IDS option of the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE
        MASTER TO</code></a> statement is deprecated when using GTIDs,
        because transactions that have already been applied are
        automatically ignored. Before starting GTID-based replication,
        check for and clear all ignored server ID lists that have
        previously been set on the servers involved. The
        <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> statement,
        which can be issued for individual channels, displays the list
        of ignored server IDs if there is one. If there is no list, the
        <code class="literal">Replicate_Ignore_Server_Ids</code> field is blank.
      </p><p><a name="replication-gtids-restrictions-mysqldump"></a><b>GTID mode and mysqldump. </b>
        It is possible to import a dump made using
        <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> into a MySQL server running with
        GTID mode enabled, provided that there are no GTIDs in the
        target server's binary log.
      </p><p><a name="replication-gtids-restrictions-mysql_upgrade"></a><b>GTID mode and mysql_upgrade. </b>
        Prior to MySQL 8.0.16, when the server is running with global
        transaction identifiers (GTIDs) enabled
        (<a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>), do not enable
        binary logging by <a class="link" href="programs.html#mysql-upgrade" title="4.4.5 mysql_upgrade — Check and Upgrade MySQL Tables"><span class="command"><strong>mysql_upgrade</strong></span></a> (the
        <a class="link" href="programs.html#option_mysql_upgrade_write-binlog"><code class="option">--write-binlog</code></a> option). As
        of MySQL 8.0.16, the server performs the entire MySQL upgrade
        procedure, but disables binary logging during the upgrade, so
        there is no issue.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-gtids-functions"></a>17.1.3.7 Stored Function Examples to Manipulate GTIDs</h4>

</div>

</div>

</div>
<p>
      MySQL includes some built-in (native) functions for use with
      GTID-based replication. These functions are as follows:
</p>
<div class="variablelist">
<dl class="variablelist"><dt><span class="term">
          <code class="function">GTID_SUBSET(<em class="replaceable"><code>set1</code></em>,<em class="replaceable"><code>set2</code></em>)</code>
        </span></dt><dd><p>
            Given two sets of global transaction identifiers
            <em class="replaceable"><code>set1</code></em> and
            <em class="replaceable"><code>set2</code></em>, returns true if all GTIDs
            in <em class="replaceable"><code>set1</code></em> are also in
            <em class="replaceable"><code>set2</code></em>. Returns false otherwise.
          </p></dd><dt><span class="term">
          <code class="function">GTID_SUBTRACT(<em class="replaceable"><code>set1</code></em>,<em class="replaceable"><code>set2</code></em>)</code>
        </span></dt><dd><p>
            Given two sets of global transaction identifiers
            <em class="replaceable"><code>set1</code></em> and
            <em class="replaceable"><code>set2</code></em>, returns only those GTIDs
            from <em class="replaceable"><code>set1</code></em> that are not in
            <em class="replaceable"><code>set2</code></em>.
          </p></dd><dt><span class="term">
          <code class="function">WAIT_FOR_EXECUTED_GTID_SET(<em class="replaceable"><code>gtid_set</code></em>[,
          <em class="replaceable"><code>timeout</code></em>])</code>
        </span></dt><dd><p>
            Wait until the server has applied all of the transactions
            whose global transaction identifiers are contained in
            <em class="replaceable"><code>gtid_set</code></em>. The optional timeout
            stops the function from waiting after the specified number
            of seconds have elapsed.
</p></dd></dl>
</div>
<p>
      For details of these functions, see
      <a class="xref" href="functions.html#gtid-functions" title="12.18 Functions Used with Global Transaction Identifiers (GTIDs)">Section 12.18, “Functions Used with Global Transaction Identifiers (GTIDs)”</a>.
    </p><p>
      You can define your own stored functions to work with GTIDs. For
      information on defining stored functions, see
      <a class="xref" href="stored-objects.html" title="Chapter 24 Stored Objects">Chapter 24, <i>Stored Objects</i></a>. The following examples show some
      useful stored functions that can be created based on the built-in
      <code class="function">GTID_SUBSET()</code> and
      <code class="function">GTID_SUBTRACT()</code> functions.
    </p><p>
      Note that in these stored functions, the delimiter command has
      been used to change the MySQL statement delimiter to a vertical
      bar, as follows:

</p><pre data-lang="sql" class="programlisting">mysql&gt; delimiter |</pre><p>
    </p><p>
      All of these functions take string representations of GTID sets as
      arguments, so GTID sets must always be quoted when used with them.
    </p><p>
      This function returns nonzero (true) if two GTID sets are the same
      set, even if they are not formatted in the same way.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_IS_EQUAL(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT)
RETURNS INT
  RETURN GTID_SUBSET(gtid_set_1, gtid_set_2) AND GTID_SUBSET(gtid_set_2, gtid_set_1)|</pre><p>
    </p><p>
      This function returns nonzero (true) if two GTID sets are
      disjoint.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_IS_DISJOINT(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT)
RETURNS INT
  RETURN GTID_SUBSET(gtid_set_1, GTID_SUBTRACT(gtid_set_1, gtid_set_2))|</pre><p>
    </p><p>
      This function returns nonzero (true) if two GTID sets are
      disjoint, and <code class="literal">sum</code> is the union of the two sets.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_IS_DISJOINT_UNION(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT, sum LONGTEXT)
RETURNS INT
  RETURN GTID_IS_EQUAL(GTID_SUBTRACT(sum, gtid_set_1), gtid_set_2) AND
         GTID_IS_EQUAL(GTID_SUBTRACT(sum, gtid_set_2), gtid_set_1)|</pre><p>
    </p><p>
      This function returns a normalized form of the GTID set, in all
      uppercase, with no whitespace and no duplicates. The UUIDs are
      arranged in alphabetic order and intervals are arranged in numeric
      order.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_NORMALIZE(g LONGTEXT)
RETURNS LONGTEXT
RETURN GTID_SUBTRACT(g, '')|</pre><p>
    </p><p>
      This function returns the union of two GTID sets.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_UNION(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT)
RETURNS LONGTEXT
  RETURN GTID_NORMALIZE(CONCAT(gtid_set_1, ',', gtid_set_2))|</pre><p>
    </p><p>
      This function returns the intersection of two GTID sets.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_INTERSECTION(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT)
RETURNS LONGTEXT
  RETURN GTID_SUBTRACT(gtid_set_1, GTID_SUBTRACT(gtid_set_1, gtid_set_2))|</pre><p>
    </p><p>
      This function returns the symmetric difference between two GTID
      sets, that is, the GTIDs that exist in
      <code class="literal">gtid_set_1</code> but not in
      <code class="literal">gtid_set_2</code>, and also the GTIDs that exist in
      <code class="literal">gtid_set_2</code> but not in
      <code class="literal">gtid_set_1</code>.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_SYMMETRIC_DIFFERENCE(gtid_set_1 LONGTEXT, gtid_set_2 LONGTEXT)
RETURNS LONGTEXT
  RETURN GTID_SUBTRACT(CONCAT(gtid_set_1, ',', gtid_set_2), GTID_INTERSECTION(gtid_set_1, gtid_set_2))|</pre><p>
    </p><p>
      This function removes from a GTID set all the GTIDs from a
      specified origin, and returns the remaining GTIDs, if any. The
      UUID is the identifier used by the server where the transaction
      originated, which is normally the
      <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> value.

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_SUBTRACT_UUID(gtid_set LONGTEXT, uuid TEXT)
RETURNS LONGTEXT
  RETURN GTID_SUBTRACT(gtid_set, CONCAT(UUID, ':1-', (1 &lt;&lt; 63) - 2))|</pre><p>
    </p><p>
      This function reverses the previously listed function to return
      only those GTIDs from the GTID set that originate from the server
      with the specified identifier (UUID).

</p><pre data-lang="sql" class="programlisting">CREATE FUNCTION GTID_INTERSECTION_WITH_UUID(gtid_set LONGTEXT, uuid TEXT)
RETURNS LONGTEXT
  RETURN GTID_SUBTRACT(gtid_set, GTID_SUBTRACT_UUID(gtid_set, uuid))|</pre><p>
</p>
<div class="example">
<a name="idm46444271087888"></a><p class="title"><b>Example 17.1 Verifying that a replication slave is up to date</b></p>
<div class="example-contents">
<p>
        The built-in functions <code class="function">GTID_SUBSET</code> and
        <code class="function">GTID_SUBTRACT</code> can be used to check that a
        replication slave has applied at least every transaction that a
        master has applied.
      </p><p>
        To perform this check with <code class="function">GTID_SUBSET</code>,
        execute the following statement on the slave:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_SUBSET(<em class="replaceable"><code>master_gtid_executed</code></em>, <em class="replaceable"><code>slave_gtid_executed</code></em>)</pre><p>

        If this returns 0 (false), some GTIDs in
        <em class="replaceable"><code>master_gtid_executed</code></em> are not present
        in <em class="replaceable"><code>slave_gtid_executed</code></em>, so the master
        has applied some transactions that the slave has not applied,
        and the slave is therefore not up to date.
      </p><p>
        To perform the check with <code class="function">GTID_SUBTRACT</code>,
        execute the following statement on the slave:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_SUBTRACT(<em class="replaceable"><code>master_gtid_executed</code></em>, <em class="replaceable"><code>slave_gtid_executed</code></em>)</pre><p>

        This statement returns any GTIDs that are in
        <em class="replaceable"><code>master_gtid_executed</code></em> but not in
        <em class="replaceable"><code>slave_gtid_executed</code></em>. If any GTIDs are
        returned, the master has applied some transactions that the
        slave has not applied, and the slave is therefore not up to
        date.
</p>
</div>

</div>
<br class="example-break">
<div class="example">
<a name="idm46444271076896"></a><p class="title"><b>Example 17.2 Backup and restore scenario</b></p>
<div class="example-contents">
<p>
        The stored functions <code class="function">GTID_IS_EQUAL</code>,
        <code class="function">GTID_IS_DISJOINT</code>, and
        <code class="function">GTID_IS_DISJOINT_UNION</code> could be used to
        verify backup and restore operations involving multiple
        databases and servers. In this example scenario,
        <code class="literal">server1</code> contains database
        <code class="literal">db1</code>, and <code class="literal">server2</code> contains
        database <code class="literal">db2</code>. The goal is to copy database
        <code class="literal">db2</code> to <code class="literal">server1</code>, and the
        result on <code class="literal">server1</code> should be the union of the
        two databases. The procedure used is to back up
        <code class="literal">server2</code> using <a class="link" href="programs.html#mysqlpump" title="4.5.6 mysqlpump — A Database Backup Program"><span class="command"><strong>mysqlpump</strong></span></a> or
        <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>, then restore this backup on
        <code class="literal">server1</code>.
      </p><p>
        Provided the backup program's option
        <code class="option">--set-gtid-purged</code> was set to
        <code class="literal">ON</code> or the default of <code class="literal">AUTO</code>,
        the program's output contains a <code class="literal">SET
        @@GLOBAL.gtid_purged</code> statement that will add the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set from
        <code class="literal">server2</code> to the
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set on
        <code class="literal">server1</code>. The
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set contains the
        GTIDs of all the transactions that have been committed on a
        server but do not exist in any binary log file on the server.
        When database <code class="literal">db2</code> is copied to
        <code class="literal">server1</code>, the GTIDs of the transactions
        committed on <code class="literal">server2</code>, which are not in the
        binary log files on <code class="literal">server1</code>, must be added to
        <code class="literal">server1</code>'s
        <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set to make the set
        complete.
      </p><p>
        The stored functions can be used to assist with the following
        steps in this scenario:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Use <code class="function">GTID_IS_EQUAL</code> to verify that the
            backup operation computed the correct GTID set for the
            <code class="literal">SET @@GLOBAL.gtid_purged</code> statement. On
            <code class="literal">server2</code>, extract that statement from the
            <a class="link" href="programs.html#mysqlpump" title="4.5.6 mysqlpump — A Database Backup Program"><span class="command"><strong>mysqlpump</strong></span></a> or <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>
            output, and store the GTID set into a local variable, such
            as <code class="varname">$gtid_purged_set</code>. Then execute the
            following statement:

</p><pre data-lang="sql" class="programlisting">server2&gt; SELECT GTID_IS_EQUAL($gtid_purged_set, @@GLOBAL.gtid_executed); </pre><p>

            If the result is 1, the two GTID sets are equal, and the set
            has been computed correctly.
          </p></li><li class="listitem"><p>
            Use <code class="function">GTID_IS_DISJOINT</code> to verify that the
            GTID set in the <a class="link" href="programs.html#mysqlpump" title="4.5.6 mysqlpump — A Database Backup Program"><span class="command"><strong>mysqlpump</strong></span></a> or
            <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> output does not overlap with
            the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on
            <code class="literal">server1</code>. If there is any overlap, with
            identical GTIDs present on both servers for some reason, you
            will see errors when copying database <code class="literal">db2</code>
            to <code class="literal">server1</code>. To check, on
            <code class="literal">server1</code>, extract and store the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set from the
            output into a local variable as above, then execute the
            following statement:

</p><pre data-lang="sql" class="programlisting">server1&gt; SELECT GTID_IS_DISJOINT($gtid_purged_set, @@GLOBAL.gtid_executed); </pre><p>

            If the result is 1, there is no overlap between the two GTID
            sets, so no duplicate GTIDs are present.
          </p></li><li class="listitem"><p>
            Use <code class="function">GTID_IS_DISJOINT_UNION</code> to verify
            that the restore operation resulted in the correct GTID
            state on <code class="literal">server1</code>. Before restoring the
            backup, on <code class="literal">server1</code>, obtain the existing
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set by
            executing the following statement:

</p><pre data-lang="sql" class="programlisting">server1&gt; SELECT @@GLOBAL.gtid_executed;</pre><p>

            Store the result in a local variable
            <code class="varname">$original_gtid_executed</code>. Also store the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set in a local
            variable as described above. When the backup from
            <code class="literal">server2</code> has been restored onto
            <code class="literal">server1</code>, execute the following statement
            to verify the GTID state:

</p><pre data-lang="sql" class="programlisting">server1&gt; SELECT GTID_IS_DISJOINT_UNION($original_gtid_executed, 
                                       $gtid_purged_set, 
                                       @@GLOBAL.gtid_executed); </pre><p>

            If the result is 1, the stored function has verified that
            the original <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
            set from <code class="literal">server1</code>
            (<code class="varname">$original_gtid_executed</code>) and the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set that was
            added from <code class="literal">server2</code>
            (<code class="varname">$gtid_purged_set</code>) have no overlap, and
            also that the updated
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on
            <code class="literal">server1</code> now consists of the previous
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set from
            <code class="literal">server1</code> plus the
            <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set from
            <code class="literal">server2</code>, which is the desired result.
            Ensure that this check is carried out before any further
            transactions take place on <code class="literal">server1</code>,
            otherwise the new transactions in the
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set will
            cause it to fail.
</p></li></ul>
</div>

</div>

</div>
<br class="example-break">
<div class="example">
<a name="idm46444271008560"></a><p class="title"><b>Example 17.3 Selecting the most up-to-date slave for manual failover</b></p>
<div class="example-contents">
<p>
        The stored function <code class="function">GTID_UNION</code> could be
        used to identify the most up-to-date replication slave from a
        set of slaves, in order to perform a manual failover operation
        after a replication master has stopped unexpectedly. If some of
        the slaves are experiencing replication lag, this stored
        function can be used to compute the most up-to-date slave
        without waiting for all the slaves to apply their existing relay
        logs, and therefore to minimize the failover time. The function
        can return the union of the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on each slave
        with the set of transactions received by the slave, which is
        recorded in the Performance Schema table
        <a class="link" href="performance-schema.html#replication-connection-status-table" title="26.12.11.2 The replication_connection_status Table"><code class="literal">replication_connection_status</code></a>. You
        can compare these results to find which slave's record of
        transactions is the most up-to-date, even if not all of the
        transactions have been committed yet.
      </p><p>
        On each replication slave, compute the complete record of
        transactions by issuing the following statement:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_UNION(RECEIVED_TRANSACTION_SET, @@GLOBAL.gtid_executed) 
    FROM performance_schema.replication_connection_status 
    WHERE channel_name = 'name';</pre><p>

        You can then compare the results from each slave to see which
        one has the most up-to-date record of transactions, and use this
        slave as the new replication master.
</p>
</div>

</div>
<br class="example-break">
<div class="example">
<a name="idm46444271001248"></a><p class="title"><b>Example 17.4 Checking for extraneous transactions on a replication slave</b></p>
<div class="example-contents">
<p>
        The stored function <code class="function">GTID_SUBTRACT_UUID</code>
        could be used to check whether a replication slave has received
        transactions that did not originate from its designated master
        or masters. If it has, there might be an issue with your
        replication setup, or with a proxy, router, or load balancer.
        This function works by removing from a GTID set all the GTIDs
        from a specified originating server, and returning the remaining
        GTIDs, if any.
      </p><p>
        For a replication slave with a single master, issue the
        following statement, giving the identifier of the originating
        replication master, which is normally the
        <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> value:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_SUBTRACT_UUID(@@GLOBAL.gtid_executed, server_uuid_of_master);</pre><p>

          If the result is not empty, the transactions returned are
        extra transactions that did not originate from the designated
        master.
      </p><p>
        For a slave in a multi-master replication topology, repeat the
        function, for example:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_SUBTRACT_UUID(GTID_SUBTRACT_UUID(@@GLOBAL.gtid_executed,
                                             server_uuid_of_master_1),
                                             server_uuid_of_master_2);</pre><p>

        If the result is not empty, the transactions returned are extra
        transactions that did not originate from any of the designated
        masters.
</p>
</div>

</div>
<br class="example-break">
<div class="example">
<a name="idm46444270993552"></a><p class="title"><b>Example 17.5 Verifying that a server in a replication topology is read-only</b></p>
<div class="example-contents">
<p>
        The stored function
        <code class="function">GTID_INTERSECTION_WITH_UUID</code> could be used
        to verify that a server has not originated any GTIDs and is in a
        read-only state. The function returns only those GTIDs from the
        GTID set that originate from the server with the specified
        identifier. If any of the transactions in the server's
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set have the
        server's own identifier, the server itself originated those
        transactions. You can issue the following statement on the
        server to check:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_INTERSECTION_WITH_UUID(@@GLOBAL.gtid_executed, my_server_uuid);</pre><p>
</p>
</div>

</div>
<br class="example-break">
<div class="example">
<a name="idm46444270988864"></a><p class="title"><b>Example 17.6 Validating an additional slave in a multi-master replication setup</b></p>
<div class="example-contents">
<p>
        The stored function
        <code class="function">GTID_INTERSECTION_WITH_UUID</code> could be used
        to find out if a slave attached to a multi-master replication
        setup has applied all the transactions originating from one
        particular master. In this scenario, <code class="literal">master1</code>
        and <code class="literal">master2</code> are both masters and slaves and
        replicate to each other. <code class="literal">master2</code> also has its
        own replication slave. The replication slave will also receive
        and apply <code class="literal">master1</code>'s transactions if
        <code class="literal">master2</code> is configured with
        <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates=ON</code></a>, but it
        will not do so if <code class="literal">master2</code> uses
        <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates=OFF</code></a>. Whatever
        the case, we currently only want to find out if the replication
        slave is up to date with <code class="literal">master2</code>. In this
        situation, the stored function
        <code class="function">GTID_INTERSECTION_WITH_UUID</code> can be used to
        identify the transactions that <code class="literal">master2</code>
        originated, discarding the transactions that
        <code class="literal">master2</code> has replicated from
        <code class="literal">master1</code>. The built-in function
        <code class="function">GTID_SUBSET</code> can then be used to compare the
        result to the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set
        on the slave. If the slave is up to date with
        <code class="literal">master2</code>, the
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set on the slave
        contains all the transactions in the intersection set (the
        transactions that originated from <code class="literal">master2</code>).
      </p><p>
        To carry out this check, store <code class="literal">master2</code>'s
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set,
        <code class="literal">master2</code>'s server UUID, and the slave's
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set, into
        client-side variables as follows:

</p><pre data-lang="sql" class="programlisting">    $master2_gtid_executed :=
      master2&gt; SELECT @@GLOBAL.gtid_executed;
    $master2_server_uuid :=
      master2&gt; SELECT @@GLOBAL.server_uuid;
    $slave_gtid_executed :=
      slave&gt; SELECT @@GLOBAL.gtid_executed;</pre><p>

        Then use <code class="function">GTID_INTERSECTION_WITH_UUID</code> and
        <code class="function">GTID_SUBSET</code> with these variables as input,
        as follows:

</p><pre data-lang="sql" class="programlisting">SELECT GTID_SUBSET(GTID_INTERSECTION_WITH_UUID($master2_gtid_executed,
                                               $master2_server_uuid),
                                               $slave_gtid_executed);</pre><p>
      </p><p>
        The server identifier from <code class="literal">master2</code>
        (<code class="varname">$master2_server_uuid</code>) is used with
        <code class="literal">GTID_INTERSECTION_WITH_UUID</code> to identify and
        return only those GTIDs from <code class="literal">master2</code>'s
        <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set that
        originated on <code class="literal">master2</code>, omitting those that
        originated on <code class="literal">master1</code>. The resulting GTID set
        is then compared with the set of all executed GTIDs on the
        slave, using <code class="function">GTID_SUBSET</code>. If this statement
        returns nonzero (true), all the identified GTIDs from
        <code class="literal">master2</code> (the first set input) are also in the
        slave's <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set (the
        second set input), meaning that the slave has replicated all the
        transactions that originated from <code class="literal">master2</code>.
</p>
</div>

</div>
<br class="example-break">
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-multi-source"></a>17.1.4 MySQL Multi-Source Replication</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-multi-source-configuration">17.1.4.1 Configuring Multi-Source Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-provision-slave">17.1.4.2 Provisioning a Multi-Source Replication Slave for GTID-Based Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-adding-gtid-master">17.1.4.3 Adding GTID-Based Masters to a Multi-Source Replication Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-adding-binlog-master">17.1.4.4 Adding Binary Log Based Replication Masters to a Multi-Source
Replication Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-start-slave">17.1.4.5 Starting Multi-Source Replication Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-stop-slave">17.1.4.6 Stopping Multi-Source Replication Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-reset-slave">17.1.4.7 Resetting Multi-Source Replication Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-multi-source-monitoring">17.1.4.8 Monitoring Multi-Source Replication</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444270951760"></a><a class="indexterm" name="idm46444270950672"></a><a class="indexterm" name="idm46444270949168"></a><a class="indexterm" name="idm46444270947664"></a><p>
    MySQL multi-source replication enables a replication slave to
    receive transactions from multiple immediate masters in parallel. In
    a multi-source replication topology, a slave creates a replication
    channel for each master that it should receive transactions from.
    For more information on how replication channels function, see
    <a class="xref" href="replication.html#replication-channels" title="17.2.3 Replication Channels">Section 17.2.3, “Replication Channels”</a>.
  </p><p>
    You might choose to implement multi-source replication to achieve
    goals like these:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Backing up multiple servers to a single server.
      </p></li><li class="listitem"><p>
        Merging table shards.
      </p></li><li class="listitem"><p>
        Consolidating data from multiple servers to a single server.
</p></li></ul>
</div>
<p>
    Multi-source replication does not implement any conflict detection
    or resolution when applying transactions, and those tasks are left
    to the application if required.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      Each channel on a multi-source replication slave must replicate
      from a different master. You cannot set up multiple replication
      channels from a single slave to a single master. This is because
      the server IDs of replication slaves must be unique in a
      replication topology. The master distinguishes slaves only by
      their server IDs, not by the names of the replication channels, so
      it cannot recognize different replication channels from the same
      slave.
</p>
</div>
<p>
    A rmulti-source replication slave can also be set up as a
    multi-threaded replication slave, by setting the
    <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> system
    variable to a value greater than 0. When you do this on a
    multi-source replication slave, each channel on the slave has the
    specified number of applier threads, plus a coordinator thread to
    manage them. You cannot configure the number of applier threads for
    individual channels.
  </p><p>
    From MySQL 8.0, multi-source replication slaves can be configured
    with replication filters on specific replication channels. Channel
    specific replication filters can be used when the same database or
    table is present on multiple masters, and you only need the slave to
    replicate it from one master. For more information, see
    <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>.
  </p><p>
    This section provides tutorials on how to configure masters and
    slaves for multi-source replication, how to start, stop and reset
    multi-source slaves, and how to monitor multi-source replication.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-configuration"></a>17.1.4.1 Configuring Multi-Source Replication</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444270934112"></a><p>
      A multi-source replication topology requires at least two masters
      and one slave configured. In these tutorials, we will assume you
      have two masters <code class="literal">master1</code> and
      <code class="literal">master2</code>, and a replication slave
      <code class="literal">slavehost</code>. The slave will replicate one
      database from each of the masters, <code class="literal">db1</code> from
      <code class="literal">master1</code> and <code class="literal">db2</code> from
      <code class="literal">master2</code>.
    </p><p>
      Masters in a multi-source replication topology can be configured
      to use either GTID-based replication, or binary log position-based
      replication. See <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a> for how
      to configure a master using GTID-based replication. See
      <a class="xref" href="replication.html#replication-howto-masterbaseconfig" title="17.1.2.1 Setting the Replication Master Configuration">Section 17.1.2.1, “Setting the Replication Master Configuration”</a> for how to
      configure a master using file position based replication.
    </p><p>
      Slaves in a multi-source replication topology require
      <code class="literal">TABLE</code> repositories for the master info log and
      relay log info log, which are the default in MySQL
      8.0. Multi-source replication is not compatible with
      file repositories, and the <code class="literal">FILE</code> setting for the
      <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository</code></a> and
      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a> system
      variables is now deprecated.
    </p><p>
      To modify an existing replication slave that is using a
      <code class="literal">FILE</code> repository for the slave status logs to
      use <code class="literal">TABLE</code> repositories, you can convert the
      existing replication repositories dynamically by using the
      <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the following statements
      on the slave:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP SLAVE;</code></strong>
mysql&gt; <strong class="userinput"><code>SET GLOBAL master_info_repository = 'TABLE';</code></strong>
mysql&gt; <strong class="userinput"><code>SET GLOBAL relay_log_info_repository = 'TABLE';</code></strong>
</pre><p>
      Create a suitable user account on all the masters that the slave
      can use to connect. You can use the same account on all the
      masters, or a different account on each. If you create an account
      solely for the purposes of replication, that account needs only
      the <a class="link" href="security.html#priv_replication-slave"><code class="literal">REPLICATION SLAVE</code></a> privilege.
      For example, to set up a new user, <code class="literal">ted</code>, that
      can connect from the replication slave
      <code class="literal">slavehost</code>, use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>
      client to issue these statements on each of the masters:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CREATE USER 'ted'@'slavehost' IDENTIFIED BY '<em class="replaceable"><code>password</code></em>';</code></strong>
mysql&gt; <strong class="userinput"><code>GRANT REPLICATION SLAVE ON *.* TO 'ted'@'slavehost';</code></strong>
</pre><p>
      For more details, and important information on the default
      authentication plugin for new users from MySQL 8.0, see
      <a class="xref" href="replication.html#replication-howto-repuser" title="17.1.2.3 Creating a User for Replication">Section 17.1.2.3, “Creating a User for Replication”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-provision-slave"></a>17.1.4.2 Provisioning a Multi-Source Replication Slave for GTID-Based Replication</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270903616"></a><p>
      If the masters in the multi-source replication topology have
      existing data, it can save time to provision the slave with the
      relevant data before starting replication. In a multi-source
      replication topology, cloning or copying of the data directory
      cannot be used to provision the slave with data from all of the
      masters, and you might also want to replicate only specific
      databases from each master. The best strategy for provisioning
      such a slave is therefore to use <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> to
      create an appropriate dump file on each master, then use the
      <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to import the dump file on the
      slave.
    </p><p>
      If you are using GTID-based replication, you need to pay attention
      to the <code class="literal">SET @@GLOBAL.gtid_purged</code> statement that
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> places in the dump output. This
      statement transfers the GTIDs for the transactions executed on the
      master to the slave, and the slave requires this information.
      However, for any case more complex than provisioning one new,
      empty slave from one master, you need to check what effect the
      statement will have in the slave's MySQL release, and handle the
      statement accordingly. The following guidance summarizes suitable
      actions, but for more details, see the
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> documentation.
    </p><p>
      The behavior of the <code class="literal">SET @@GLOBAL.gtid_purged</code>
      statement written by <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> is different in
      releases from MySQL 8.0 compared to MySQL 5.6 and 5.7. In MySQL
      5.6 and 5.7, the statement replaces the value of
      <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> on the slave, and
      also in those releases that value can only be changed when the
      slave's record of transactions with GTIDs (the
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set) is empty. In a
      multi-source replication topology, you must therefore remove the
      <code class="literal">SET @@GLOBAL.gtid_purged</code> statement from the
      dump output before replaying the dump files, because you will not
      be able to apply a second or subsequent dump file including this
      statement. Also note that for MySQL 5.6 and 5.7, this limitation
      means all the dump files from the masters must be applied in a
      single operation on a slave with an empty
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> set. You can clear
      a slave's GTID execution history by issuing
      <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> on the slave, but if
      you have other, wanted transactions with GTIDs on the slave,
      choose an alternative method of provisioning from those described
      in <a class="xref" href="replication.html#replication-gtids-failover" title="17.1.3.5 Using GTIDs for Failover and Scaleout">Section 17.1.3.5, “Using GTIDs for Failover and Scaleout”</a>.
    </p><p>
      From MySQL 8.0, the <code class="literal">SET @@GLOBAL.gtid_purged</code>
      statement adds the GTID set from the dump file to the existing
      <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> set on the slave. The
      statement can therefore potentially be left in the dump output
      when you replay the dump files on the slave, and the dump files
      can be replayed at different times. However, it is important to
      note that the value that is included by
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> for the <code class="literal">SET
      @@GLOBAL.gtid_purged</code> statement includes the GTIDs of all
      transactions in the <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
      set on the master, even those that changed suppressed parts of the
      database, or other databases on the server that were not included
      in a partial dump. If you replay a second or subsequent dump file
      on the slave that contains any of the same GTIDs (for example,
      another partial dump from the same master, or a dump from another
      master that has overlapping transactions), any <code class="literal">SET
      @@GLOBAL.gtid_purged</code> statement in the second dump file
      will fail, and must therefore be removed from the dump output.
    </p><p>
      For masters from MySQL 8.0.17, as an alternative to removing the
      <code class="literal">SET @@GLOBAL.gtid_purged</code> statement, you may set
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>'s
      <code class="literal">--set-gtid-purged</code> option to
      <code class="literal">COMMENTED</code> to include the statement but
      commented out, so that it is not actioned when you load the dump
      file. If you are provisioning the slave with two partial dumps
      from the same master, and the GTID set in the second dump is the
      same as the first (so no new transactions have been executed on
      the master in between the dumps), you can set
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>'s
      <code class="literal">--set-gtid-purged</code> option to
      <code class="literal">OFF</code> when you output the second dump file, to
      omit the statement.
    </p><p>
      In the following provisioning example, we assume that the
      <code class="literal">SET @@GLOBAL.gtid_purged</code> statement cannot be
      left in the dump output, and must be removed from the files and
      handled manually. We also assume that there are no wanted
      transactions with GTIDs on the slave before provisioning starts.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          To create dump files for a database named
          <code class="literal">db1</code> on <code class="literal">master1</code> and a
          database named <code class="literal">db2</code> on
          <code class="literal">master2</code>, run <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>
          for <code class="literal">master1</code> as follows:
        </p><pre data-lang="shell" class="programlisting"><strong class="userinput"><code>mysqldump -u&lt;<em class="replaceable"><code>user</code></em>&gt; -p&lt;<em class="replaceable"><code>password</code></em>&gt; --single-transaction --triggers --routines --set-gtid-purged=ON --databases db1 &gt; dumpM1.sql </code></strong>
</pre><p>
          Then run <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> for
          <code class="literal">master2</code> as follows:
        </p><pre data-lang="shell" class="programlisting"><strong class="userinput"><code>mysqldump -u&lt;<em class="replaceable"><code>user</code></em>&gt; -p&lt;<em class="replaceable"><code>password</code></em>&gt; --single-transaction --triggers --routines --set-gtid-purged=ON --databases db2 &gt; dumpM2.sql </code></strong>
</pre></li><li class="listitem"><p>
          Record the <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> value
          that <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> added to each of the dump
          files. For example, for dump files created on MySQL 5.6 or
          5.7, you can extract the value like this:
        </p><pre data-lang="none" class="programlisting"><strong class="userinput"><code>cat dumpM1.sql | grep GTID_PURGED | cut -f2 -d'=' | cut -f2 -d$'\''</code></strong>
<strong class="userinput"><code>cat dumpM2.sql | grep GTID_PURGED | cut -f2 -d'=' | cut -f2 -d$'\'' </code></strong>
</pre><p>
          From MySQL 8.0, where the format has changed, you can extract
          the value like this:
        </p><pre data-lang="none" class="programlisting"><strong class="userinput"><code>cat dumpM1.sql | grep GTID_PURGED | perl -p0 -e 's#/\*.*?\*/##sg' | cut -f2 -d'=' | cut -f2 -d$'\''</code></strong>
<strong class="userinput"><code>cat dumpM2.sql | grep GTID_PURGED | perl -p0 -e 's#/\*.*?\*/##sg' | cut -f2 -d'=' | cut -f2 -d$'\''</code></strong>
</pre><p>
          The result in each case should be a GTID set, for example:
        </p><pre data-lang="none" class="programlisting">master1:   2174B383-5441-11E8-B90A-C80AA9429562:1-1029
master2:   224DA167-0C0C-11E8-8442-00059A3C7B00:1-2695</pre></li><li class="listitem"><p>
          Remove the line from each dump file that contains the
          <code class="literal">SET @@GLOBAL.gtid_purged</code> statement. For
          example:
        </p><pre data-lang="shell" class="programlisting"><strong class="userinput"><code>sed '/GTID_PURGED/d' dumpM1.sql &gt; dumpM1_nopurge.sql</code></strong>
<strong class="userinput"><code>sed '/GTID_PURGED/d' dumpM2.sql &gt; dumpM2_nopurge.sql </code></strong>
</pre></li><li class="listitem"><p>
          Use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to import each edited
          dump file into the slave. For example:
        </p><pre data-lang="shell" class="programlisting"><strong class="userinput"><code>mysql -u&lt;<em class="replaceable"><code>user</code></em>&gt; -p&lt;<em class="replaceable"><code>password</code></em>&gt; &lt; dumpM1_nopurge.sql</code></strong>
<strong class="userinput"><code>mysql -u&lt;<em class="replaceable"><code>user</code></em>&gt; -p&lt;<em class="replaceable"><code>password</code></em>&gt; &lt; dumpM2_nopurge.sql </code></strong>
</pre></li><li class="listitem"><p>
          On the slave, issue <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET
          MASTER</code></a> to clear the GTID execution history
          (assuming, as explained above, that all the dump files have
          been imported and that there are no wanted transactions with
          GTIDs on the slave). Then issue a <code class="literal">SET
          @@GLOBAL.gtid_purged</code> statement to set the
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> value to the
          union of all the GTID sets from all the dump files, as you
          recorded in Step 2. For example:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>RESET MASTER;</code></strong>
mysql&gt; <strong class="userinput"><code>SET @@GLOBAL.gtid_purged = "2174B383-5441-11E8-B90A-C80AA9429562:1-1029, 224DA167-0C0C-11E8-8442-00059A3C7B00:1-2695";</code></strong>
</pre><p>
          If there are, or might be, overlapping transactions between
          the GTID sets in the dump files, you can use the stored
          functions described in
          <a class="xref" href="replication.html#replication-gtids-functions" title="17.1.3.7 Stored Function Examples to Manipulate GTIDs">Section 17.1.3.7, “Stored Function Examples to Manipulate GTIDs”</a> to check this
          beforehand and to calculate the union of all the GTID sets.
</p></li></ol>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-adding-gtid-master"></a>17.1.4.3 Adding GTID-Based Masters to a Multi-Source Replication Slave</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270825536"></a><p>
      These steps assume you have enabled GTIDs for transactions on the
      masters using <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>,
      created a replication user, ensured that the slave is using
      <code class="literal">TABLE</code> based replication repositories, and
      provisioned the slave with data from the masters if appropriate.
    </p><p>
      Use the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
      to configure a replication channel for each master on the
      replication slave (see <a class="xref" href="replication.html#replication-channels" title="17.2.3 Replication Channels">Section 17.2.3, “Replication Channels”</a>).
      The <code class="literal">FOR CHANNEL</code> clause is used to specify the
      channel. For GTID-based replication, GTID auto-positioning is used
      to synchronize with the master (see
      <a class="xref" href="replication.html#replication-gtids-auto-positioning" title="17.1.3.3 GTID Auto-Positioning">Section 17.1.3.3, “GTID Auto-Positioning”</a>). The
      <code class="literal">MASTER_AUTO_POSITION</code> option is set to specify
      the use of auto-positioning.
    </p><p>
      For example, to add <code class="literal">master1</code> and
      <code class="literal">master2</code> as masters to the replication slave,
      use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement twice on
      the slave, like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO MASTER_HOST="master1", MASTER_USER="ted", \
MASTER_PASSWORD="<em class="replaceable"><code>password</code></em>", MASTER_AUTO_POSITION=1 FOR CHANNEL "master_1";</code></strong>
mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO MASTER_HOST="master2", MASTER_USER="ted", \
MASTER_PASSWORD="<em class="replaceable"><code>password</code></em>", MASTER_AUTO_POSITION=1 FOR CHANNEL "master_2";</code></strong>
</pre><p>
      For the full syntax of the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement and other available options, see
      <a class="xref" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement">Section 13.4.2.1, “CHANGE MASTER TO Statement”</a>.
    </p><p>
      To make the replication slave replicate only database
      <code class="literal">db1</code> from <code class="literal">master1</code>, and only
      database <code class="literal">db2</code> from <code class="literal">master2</code>,
      use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the
      <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION FILTER</code></a> statement
      for each channel, like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE REPLICATION FILTER REPLICATE_WILD_DO_TABLE = ('db1.%') FOR CHANNEL "master_1";</code></strong>
mysql&gt; <strong class="userinput"><code>CHANGE REPLICATION FILTER REPLICATE_WILD_DO_TABLE = ('db2.%') FOR CHANNEL "master_2";</code></strong>
</pre><p>
      For the full syntax of the <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION
      FILTER</code></a> statement and other available options, see
      <a class="xref" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement">Section 13.4.2.2, “CHANGE REPLICATION FILTER Statement”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-adding-binlog-master"></a>17.1.4.4 Adding Binary Log Based Replication Masters to a Multi-Source
Replication Slave</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444270794352"></a><p>
      These steps assume that binary logging is enabled on the master
      (which is the default), the slave is using
      <code class="literal">TABLE</code> based replication repositories (which is
      the default in MySQL 8.0), and that you have enabled
      a replication user and noted the current binary log position. You
      need to know the current <code class="literal">MASTER_LOG_FILE</code> and
      <code class="literal">MASTER_LOG_POSITION</code>.
    </p><p>
      Use the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
      to configure a replication channel for each master on the
      replication slave (see <a class="xref" href="replication.html#replication-channels" title="17.2.3 Replication Channels">Section 17.2.3, “Replication Channels”</a>).
      The <code class="literal">FOR CHANNEL</code> clause is used to specify the
      channel. For example, to add <code class="literal">master1</code> and
      <code class="literal">master2</code> as masters to the replication slave,
      use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement twice on
      the slave, like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO MASTER_HOST="master1", MASTER_USER="ted", MASTER_PASSWORD="<em class="replaceable"><code>password</code></em>", \
MASTER_LOG_FILE='master1-bin.000006', MASTER_LOG_POS=628 FOR CHANNEL "master_1";</code></strong>
mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO MASTER_HOST="master2", MASTER_USER="ted", MASTER_PASSWORD="<em class="replaceable"><code>password</code></em>", \
MASTER_LOG_FILE='master2-bin.000018', MASTER_LOG_POS=104 FOR CHANNEL "master_2";</code></strong>
</pre><p>
      For the full syntax of the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement and other available options, see
      <a class="xref" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement">Section 13.4.2.1, “CHANGE MASTER TO Statement”</a>.
    </p><p>
      To make the replication slave replicate only database
      <code class="literal">db1</code> from <code class="literal">master1</code>, and only
      database <code class="literal">db2</code> from <code class="literal">master2</code>,
      use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the
      <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION FILTER</code></a> statement
      for each channel, like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE REPLICATION FILTER REPLICATE_WILD_DO_TABLE = ('db1.%') FOR CHANNEL "master_1";</code></strong>
mysql&gt; <strong class="userinput"><code>CHANGE REPLICATION FILTER REPLICATE_WILD_DO_TABLE = ('db2.%') FOR CHANNEL "master_2";</code></strong>
</pre><p>
      For the full syntax of the <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION
      FILTER</code></a> statement and other available options, see
      <a class="xref" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement">Section 13.4.2.2, “CHANGE REPLICATION FILTER Statement”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-start-slave"></a>17.1.4.5 Starting Multi-Source Replication Slaves</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270764832"></a><p>
      Once you have added channels for all of the replication masters,
      issue a <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement to
      start replication. When you have enabled multiple channels on a
      slave, you can choose to either start all channels, or select a
      specific channel to start. For example, to start the two channels
      separately, use the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client to issue the
      following statements:
    </p><pre data-lang="sql" class="programlisting"> 
mysql&gt; <strong class="userinput"><code>START SLAVE FOR CHANNEL "master_1";</code></strong>
mysql&gt; <strong class="userinput"><code>START SLAVE FOR CHANNEL "master_2";</code></strong>
</pre><p>
      For the full syntax of the <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
      SLAVE</code></a> command and other available options, see
      <a class="xref" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement">Section 13.4.2.6, “START SLAVE Statement”</a>.
    </p><p>
      To verify that both channels have started and are operating
      correctly, you can issue <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
      STATUS</code></a> statements on the slave, for example:
    </p><pre data-lang="sql" class="programlisting"> 
mysql&gt; <strong class="userinput"><code>SHOW SLAVE STATUS FOR CHANNEL "master_1"\G</code></strong>
mysql&gt; <strong class="userinput"><code>SHOW SLAVE STATUS FOR CHANNEL "master_2"\G</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-stop-slave"></a>17.1.4.6 Stopping Multi-Source Replication Slaves</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270749936"></a><p>
      The <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> statement can be
      used to stop a multi-source replication slave. By default, if you
      use the <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> statement on a
      multi-source replication slave all channels are stopped.
      Optionally, use the <code class="literal">FOR CHANNEL
      <em class="replaceable"><code>channel</code></em></code> clause to stop only a
      specific channel.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To stop all currently configured replication channels:
        </p><pre data-lang="sql" class="programlisting"><strong class="userinput"><code>STOP SLAVE;</code></strong>
</pre></li><li class="listitem"><p>
          To stop only a named channel, use a <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause:
        </p><pre data-lang="sql" class="programlisting"> <strong class="userinput"><code>STOP SLAVE FOR CHANNEL "master_1";</code></strong>
</pre></li></ul>
</div>
<p>
      For the full syntax of the <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP
      SLAVE</code></a> command and other available options, see
      <a class="xref" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement">Section 13.4.2.7, “STOP SLAVE Statement”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-reset-slave"></a>17.1.4.7 Resetting Multi-Source Replication Slaves</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270734528"></a><p>
      The <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> statement can be
      used to reset a multi-source replication slave. By default, if you
      use the <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> statement on a
      multi-source replication slave all channels are reset. Optionally,
      use the <code class="literal">FOR CHANNEL
      <em class="replaceable"><code>channel</code></em></code> clause to reset only
      a specific channel.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To reset all currently configured replication channels:
        </p><pre data-lang="sql" class="programlisting"> <strong class="userinput"><code>RESET SLAVE;</code></strong>
</pre></li><li class="listitem"><p>
          To reset only a named channel, use a <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause:
        </p><pre data-lang="sql" class="programlisting"><strong class="userinput"><code>RESET SLAVE FOR CHANNEL "master_1";</code></strong>
</pre></li></ul>
</div>
<p>
      For GTID-based replication, note that <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET
      SLAVE</code></a> has no effect on the slave's GTID execution
      history. If you want to clear this, issue
      <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> on the slave.
    </p><p>
      <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> makes the slave forget
      its replication position, and clears the relay log, but it does
      not change any replication connection parameters (such as the
      master host) or replication filters. If you want to remove these
      for a channel, issue <code class="literal">RESET SLAVE ALL</code>.
    </p><p>
      For the full syntax of the <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET
      SLAVE</code></a> command and other available options, see
      <a class="xref" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement">Section 13.4.2.4, “RESET SLAVE Statement”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-multi-source-monitoring"></a>17.1.4.8 Monitoring Multi-Source Replication</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270713568"></a><a class="indexterm" name="idm46444270712064"></a><p>
      To monitor the status of replication channels the following
      options exist:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Using the replication Performance Schema tables. The first
          column of these tables is <code class="literal">Channel_Name</code>.
          This enables you to write complex queries based on
          <code class="literal">Channel_Name</code> as a key. See
          <a class="xref" href="performance-schema.html#performance-schema-replication-tables" title="26.12.11 Performance Schema Replication Tables">Section 26.12.11, “Performance Schema Replication Tables”</a>.
        </p></li><li class="listitem"><p>
          Using <code class="literal">SHOW SLAVE STATUS FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code>. By default, if
          the <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause is not
          used, this statement shows the slave status for all channels
          with one row per channel. The identifier
          <code class="literal">Channel_name</code> is added as a column in the
          result set. If a <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause is
          provided, the results show the status of only the named
          replication channel.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
        The <a class="link" href="sql-statements.html#show-variables" title="13.7.7.39 SHOW VARIABLES Statement"><code class="literal">SHOW VARIABLES</code></a> statement does
        not work with multiple replication channels. The information
        that was available through these variables has been migrated to
        the replication performance tables. Using a
        <a class="link" href="sql-statements.html#show-variables" title="13.7.7.39 SHOW VARIABLES Statement"><code class="literal">SHOW VARIABLES</code></a> statement in a
        topology with multiple channels shows the status of only the
        default channel.
</p>
</div>
<p>
      The error codes and messages that are issued when multi-source
      replication is enabled specify the channel that generated the
      error.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-multi-source-monitoring-tutorial"></a>17.1.4.8.1 Monitoring Channels Using Performance Schema Tables</h5>
</div>
</div>
</div>
<a class="indexterm" name="idm46444270696368"></a><p>
        This section explains how to use the replication Performance
        Schema tables to monitor channels. You can choose to monitor all
        channels, or a subset of the existing channels.
      </p><p>
        To monitor the connection status of all channels:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT * FROM replication_connection_status\G;</code></strong>
*************************** 1. row ***************************
CHANNEL_NAME: master_1
GROUP_NAME:
SOURCE_UUID: 046e41f8-a223-11e4-a975-0811960cc264
THREAD_ID: 24
SERVICE_STATE: ON
COUNT_RECEIVED_HEARTBEATS: 0
LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
RECEIVED_TRANSACTION_SET: 046e41f8-a223-11e4-a975-0811960cc264:4-37
LAST_ERROR_NUMBER: 0
LAST_ERROR_MESSAGE:
LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
*************************** 2. row ***************************
CHANNEL_NAME: master_2
GROUP_NAME:
SOURCE_UUID: 7475e474-a223-11e4-a978-0811960cc264
THREAD_ID: 26
SERVICE_STATE: ON
COUNT_RECEIVED_HEARTBEATS: 0
LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
RECEIVED_TRANSACTION_SET: 7475e474-a223-11e4-a978-0811960cc264:4-6
LAST_ERROR_NUMBER: 0
LAST_ERROR_MESSAGE:
LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
2 rows in set (0.00 sec)
	    </pre><p>
        In the above output there are two channels enabled, and as shown
        by the <code class="literal">CHANNEL_NAME</code> field they are called
        <code class="literal">master_1</code> and <code class="literal">master_2</code>.
      </p><p>
        The addition of the <code class="literal">CHANNEL_NAME</code> field
        enables you to query the Performance Schema tables for a
        specific channel. To monitor the connection status of a named
        channel, use a <code class="literal">WHERE
        CHANNEL_NAME=<em class="replaceable"><code>channel</code></em></code>
        clause:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT * FROM replication_connection_status WHERE CHANNEL_NAME='master_1'\G</code></strong>
*************************** 1. row ***************************
CHANNEL_NAME: master_1
GROUP_NAME:
SOURCE_UUID: 046e41f8-a223-11e4-a975-0811960cc264
THREAD_ID: 24
SERVICE_STATE: ON
COUNT_RECEIVED_HEARTBEATS: 0
LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
RECEIVED_TRANSACTION_SET: 046e41f8-a223-11e4-a975-0811960cc264:4-37
LAST_ERROR_NUMBER: 0
LAST_ERROR_MESSAGE:
LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
1 row in set (0.00 sec)
</pre><p>
        Similarly, the <code class="literal">WHERE
        CHANNEL_NAME=<em class="replaceable"><code>channel</code></em></code> clause
        can be used to monitor the other replication Performance Schema
        tables for a specific channel. For more information, see
        <a class="xref" href="performance-schema.html#performance-schema-replication-tables" title="26.12.11 Performance Schema Replication Tables">Section 26.12.11, “Performance Schema Replication Tables”</a>.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-mode-change-online"></a>17.1.5 Changing Replication Modes on Online Servers</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-mode-change-online-concepts">17.1.5.1 Replication Mode Concepts</a></span></dt><dt><span class="section"><a href="replication.html#replication-mode-change-online-enable-gtids">17.1.5.2 Enabling GTID Transactions Online</a></span></dt><dt><span class="section"><a href="replication.html#replication-mode-change-online-disable-gtids">17.1.5.3 Disabling GTID Transactions Online</a></span></dt><dt><span class="section"><a href="replication.html#replication-mode-change-online-verify-transactions">17.1.5.4 Verifying Replication of Anonymous Transactions</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444270681120"></a><p>
    This section describes how to change the mode of replication being
    used without having to take the server offline.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-mode-change-online-concepts"></a>17.1.5.1 Replication Mode Concepts</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444270678368"></a><p>
      To be able to safely configure the replication mode of an online
      server it is important to understand some key concepts of
      replication. This section explains these concepts and is essential
      reading before attempting to modify the replication mode of an
      online server.
    </p><p>
      The modes of replication available in MySQL rely on different
      techniques for identifying transactions which are logged. The
      types of transactions used by replication are as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          GTID transactions are identified by a global transaction
          identifier (GTID) in the form <code class="literal">UUID:NUMBER</code>.
          Every GTID transaction in a log is always preceded by a
          <code class="literal">Gtid_log_event</code>. GTID transactions can be
          addressed using either the GTID or using the file name and
          position.
        </p></li><li class="listitem"><p>
          Anonymous transactions do not have a GTID assigned, and MySQL
          ensures that every anonymous transaction in a log is preceded
          by an <code class="literal">Anonymous_gtid_log_event</code>. In previous
          versions, anonymous transactions were not preceded by any
          particular event. Anonymous transactions can only be addressed
          using file name and position.
</p></li></ul>
</div>
<p>
      When using GTIDs you can take advantage of auto-positioning and
      automatic fail-over, as well as use
      <a class="link" href="functions.html#function_wait-for-executed-gtid-set"><code class="literal">WAIT_FOR_EXECUTED_GTID_SET()</code></a>,
      <a class="link" href="server-administration.html#sysvar_session_track_gtids"><code class="literal">session_track_gtids</code></a>, and monitor
      replicated transactions using Performance Schema tables. With
      GTIDs enabled you cannot use
      <a class="link" href="replication.html#sysvar_sql_slave_skip_counter"><code class="literal">sql_slave_skip_counter</code></a>, instead
      use empty transactions.
    </p><p>
      Transactions in a relay log that was received from a master
      running a previous version of MySQL may not be preceded by any
      particular event at all, but after being replayed and logged in
      the slave's binary log, they are preceded with an
      <code class="literal">Anonymous_gtid_log_event</code>.
    </p><p>
      The ability to configure the replication mode online means that
      the <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> and
      <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a>
      variables are now both dynamic and can be set from a top-level
      statement by an account that has privileges sufficient to set
      global system variables. See
      <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>. In MySQL 5.6 and
      earlier, both of these variables could only be configured using
      the appropriate option at server start, meaning that changes to
      the replication mode required a server restart. In all versions
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> could be set to
      <code class="literal">ON</code> or <code class="literal">OFF</code>, which
      corresponded to whether GTIDs were used to identify transactions
      or not. When <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> it is
      not possible to replicate anonymous transactions, and when
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=OFF</code></a> only anonymous
      transactions can be replicated. When
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=OFF_PERMISSIVE</code></a> then
      <span class="emphasis"><em>new</em></span> transactions are anonymous while
      permitting replicated transactions to be either GTID or anonymous
      transactions. When
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON_PERMISSIVE</code></a> then
      <span class="emphasis"><em>new</em></span> transactions use GTIDs while permitting
      replicated transactions to be either GTID or anonymous
      transactions. This means it is possible to have a replication
      topology that has servers using both anonymous and GTID
      transactions. For example a master with
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> could be replicating
      to a slave with
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON_PERMISSIVE</code></a>. The
      valid values for <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> are as
      follows and in this order:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">OFF</code>
        </p></li><li class="listitem"><p>
          <code class="literal">OFF_PERMISSIVE</code>
        </p></li><li class="listitem"><p>
          <code class="literal">ON_PERMISSIVE</code>
        </p></li><li class="listitem"><p>
          <code class="literal">ON</code>
</p></li></ul>
</div>
<p>
      It is important to note that the state of
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> can only be changed by
      one step at a time based on the above order. For example, if
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is currently set to
      <code class="literal">OFF_PERMISSIVE</code>, it is possible to change to
      <code class="literal">OFF</code> or <code class="literal">ON_PERMISSIVE</code> but not
      to <code class="literal">ON</code>. This is to ensure that the process of
      changing from anonymous transactions to GTID transactions online
      is correctly handled by the server. When you switch between
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> and
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=OFF</code></a>, the GTID state (in
      other words the value of
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>) is persistent.
      This ensures that the GTID set that has been applied by the server
      is always retained, regardless of changes between types of
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>.
    </p><p>
      The fields related to GTIDs display the correct information
      regardless of the currently selected
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>. This means that fields
      which display GTID sets, such as
      <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>,
      <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>,
      <code class="literal">RECEIVED_TRANSACTION_SET</code> in the
      <a class="link" href="performance-schema.html#replication-connection-status-table" title="26.12.11.2 The replication_connection_status Table"><code class="literal">replication_connection_status</code></a>
      Performance Schema table, and the GTID related results of
      <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>, now return the
      empty string when there are no GTIDs present. Fields that display
      a single GTID, such as <code class="literal">CURRENT_TRANSACTION</code> in
      the Performance Schema
      <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>
      table, now display <code class="literal">ANONYMOUS</code> when GTID
      transactions are not being used.
    </p><p>
      Replication from a master using
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> provides the ability
      to use auto-positioning, configured using the <code class="literal">CHANGE
      MASTER TO MASTER_AUTO_POSITION = 1;</code> statement. The
      replication topology being used impacts on whether it is possible
      to enable auto-positioning or not, as this feature relies on GTIDs
      and is not compatible with anonymous transactions. An error is
      generated if auto-positioning is enabled and an anonymous
      transaction is encountered. It is strongly recommended to ensure
      there are no anonymous transactions remaining in the topology
      before enabling auto-positioning, see
      <a class="xref" href="replication.html#replication-mode-change-online-enable-gtids" title="17.1.5.2 Enabling GTID Transactions Online">Section 17.1.5.2, “Enabling GTID Transactions Online”</a>.
    </p><p>
      The valid combinations of
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> and auto-positioning on
      master and slave are shown in the following table, where the
      master's <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is shown
      on the horizontal and the slave's
      <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is on the vertical. The
      meaning of each entry is as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">Y</code>: the
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> of master and slave
          is compatible
        </p></li><li class="listitem"><p>
          <code class="literal">N</code>: the
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> of master and slave
          is not compatible
        </p></li><li class="listitem"><p>
          <code class="literal">*</code>: auto-positioning can be used with this
          combination
</p></li></ul>
</div>
<p>
</p>
<div class="table">
<a name="idm46444270604560"></a><p class="title"><b>Table 17.1 Valid Combinations of Master and Slave gtid_mode</b></p>
<div class="table-contents">
<table summary="Explains compatible (Y) and incompatible (N) combinations of master and slave GTID mode. An asterisk (*) indicates that auto-positioning can be used with this combination of GTID modes."><col width="26%"><col width="12%"><col width="24%"><col width="24%"><col width="12%"><thead><tr>
            <th scope="col"><p>
                <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              </p></th>
            <th scope="col"><p>
                Master <code class="literal">OFF</code>
              </p></th>
            <th scope="col"><p>
                Master <code class="literal">OFF_PERMISSIVE</code>
              </p></th>
            <th scope="col"><p>
                Master <code class="literal">ON_PERMISSIVE</code>
              </p></th>
            <th scope="col"><p>
                Master <code class="literal">ON</code>
              </p></th>
          </tr></thead><tbody><tr>
            <td scope="row"><p>
                Slave <code class="literal">OFF</code>
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                N
              </p></td>
            <td><p>
                N
              </p></td>
          </tr><tr>
            <td scope="row"><p>
                Slave <code class="literal">OFF_PERMISSIVE</code>
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y*
              </p></td>
          </tr><tr>
            <td scope="row"><p>
                Slave <code class="literal">ON_PERMISSIVE</code>
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y*
              </p></td>
          </tr><tr>
            <td scope="row"><p>
                Slave <code class="literal">ON</code>
              </p></td>
            <td><p>
                N
              </p></td>
            <td><p>
                N
              </p></td>
            <td><p>
                Y
              </p></td>
            <td><p>
                Y*
              </p></td>
</tr></tbody></table>
</div>

</div>
<p><br class="table-break">
    </p><p>
      The currently selected <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
      also impacts on the <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>
      variable. The following table shows the behavior of the server for
      the different values of <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
      and <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>. The meaning of
      each entry is as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">ANONYMOUS</code>: generate an anonymous
          transaction.
        </p></li><li class="listitem"><p>
          <code class="literal">Error</code>: generate an error and fail to
          execute <code class="literal">SET GTID_NEXT</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">UUID:NUMBER</code>: generate a GTID with the
          specified UUID:NUMBER.
        </p></li><li class="listitem"><p>
          <code class="literal">New GTID</code>: generate a GTID with an
          automatically generated number.
</p></li></ul>
</div>

<div class="table">
<a name="idm46444270549424"></a><p class="title"><b>Table 17.2 Valid Combinations of gtid_mode and gtid_next</b></p>
<div class="table-contents">
<table summary="Explains the behavior for each of the possible combinations of GTID mode and setting for the gtid_next variable. With gtid_next set to AUTOMATIC, the behavior also varies depending on whether binary logging is enabled or disabled."><col width="20%"><col width="20%"><col width="20%"><col width="20%"><col width="20%"><thead><tr>
          <th scope="col"></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> AUTOMATIC
            </p><p>
              binary log on
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> AUTOMATIC
            </p><p>
              binary log off
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> ANONYMOUS
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> UUID:NUMBER
            </p></th>
        </tr></thead><tbody><tr>
          <td scope="row"><p>
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              <code class="literal">OFF</code>
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td>ANONYMOUS</td>
          <td><p>
              Error
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              <code class="literal">OFF_PERMISSIVE</code>
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              UUID:NUMBER
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              <code class="literal">ON_PERMISSIVE</code>
            </p></td>
          <td><p>
              New GTID
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              UUID:NUMBER
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              <code class="literal">ON</code>
            </p></td>
          <td><p>
              New GTID
            </p></td>
          <td><p>
              ANONYMOUS
            </p></td>
          <td><p>
              Error
            </p></td>
          <td><p>
              UUID:NUMBER
            </p></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
      When the binary log is off and
      <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a> is set to
      <code class="literal">AUTOMATIC</code>, then no GTID is generated. This is
      consistent with the behavior of previous versions.

      
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-mode-change-online-enable-gtids"></a>17.1.5.2 Enabling GTID Transactions Online</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270496768"></a><p>
      This section describes how to enable GTID transactions, and
      optionally auto-positioning, on servers that are already online
      and using anonymous transactions. This procedure does not require
      taking the server offline and is suited to use in production.
      However, if you have the possibility to take the servers offline
      when enabling GTID transactions that process is easier.
    </p><p>
      Before you start, ensure that the servers meet the following
      pre-conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <span class="emphasis"><em>All</em></span> servers in your topology must use
          MySQL 5.7.6 or later. You cannot enable GTID transactions
          online on any single server unless <span class="emphasis"><em>all</em></span>
          servers which are in the topology are using this version.

          
        </p></li><li class="listitem"><p>
          All servers have <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
          set to the default value <code class="literal">OFF</code>.
</p></li></ul>
</div>
<p>
      The following procedure can be paused at any time and later
      resumed where it was, or reversed by jumping to the corresponding
      step of
      <a class="xref" href="replication.html#replication-mode-change-online-disable-gtids" title="17.1.5.3 Disabling GTID Transactions Online">Section 17.1.5.3, “Disabling GTID Transactions Online”</a>,
      the online procedure to disable GTIDs. This makes the procedure
      fault-tolerant because any unrelated issues that may appear in the
      middle of the procedure can be handled as usual, and then the
      procedure continued where it was left off.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
        It is crucial that you complete every step before continuing to
        the next step.
</p>
</div>
<p>
      To enable GTID transactions:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.ENFORCE_GTID_CONSISTENCY = WARN;</pre><p>
          Let the server run for a while with your normal workload and
          monitor the logs. If this step causes any warnings in the log,
          adjust your application so that it only uses GTID-compatible
          features and does not generate any warnings.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
            This is the first important step. You must ensure that no
            warnings are being generated in the error logs before going
            to the next step.
</p>
</div>
</li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.ENFORCE_GTID_CONSISTENCY = ON;</pre></li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = OFF_PERMISSIVE;</pre><p>
          It does not matter which server executes this statement first,
          but it is important that all servers complete this step before
          any server begins the next step.
        </p></li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = ON_PERMISSIVE;</pre><p>
          It does not matter which server executes this statement first.
        </p></li><li class="listitem"><p>
          On each server, wait until the status variable
          <code class="literal">ONGOING_ANONYMOUS_TRANSACTION_COUNT</code> is
          zero. This can be checked using:
</p><pre data-lang="sql" class="programlisting">SHOW STATUS LIKE 'ONGOING_ANONYMOUS_TRANSACTION_COUNT';</pre>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            On a replication slave, it is theoretically possible that
            this shows zero and then nonzero again. This is not a
            problem, it suffices that it shows zero once.
</p>
</div>
</li><li class="listitem"><p>
          Wait for all transactions generated up to step 5 to replicate
          to all servers. You can do this without stopping updates: the
          only important thing is that all anonymous transactions get
          replicated.
        </p><p>
          See
          <a class="xref" href="replication.html#replication-mode-change-online-verify-transactions" title="17.1.5.4 Verifying Replication of Anonymous Transactions">Section 17.1.5.4, “Verifying Replication of Anonymous Transactions”</a>
          for one method of checking that all anonymous transactions
          have replicated to all servers.
        </p></li><li class="listitem"><p>
          If you use binary logs for anything other than replication,
          for example point in time backup and restore, wait until you
          do not need the old binary logs having transactions without
          GTIDs.
        </p><p>
          For instance, after step 6 has completed, you can execute
          <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH LOGS</code></a> on the server where
          you are taking backups. Then either explicitly take a backup
          or wait for the next iteration of any periodic backup routine
          you may have set up.
        </p><p>
          Ideally, wait for the server to purge all binary logs that
          existed when step 6 was completed. Also wait for any backup
          taken before step 6 to expire.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
            This is the second important point. It is vital to
            understand that binary logs containing anonymous
            transactions, without GTIDs cannot be used after the next
            step. After this step, you must be sure that transactions
            without GTIDs do not exist anywhere in the topology.
</p>
</div>
</li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = ON;</pre></li><li class="listitem"><p>
          On each server, add <code class="literal">gtid_mode=ON</code> and
          <code class="literal">enforce_gtid_consistency=ON</code> to
          <code class="filename">my.cnf</code>.
        </p><p>
          You are now guaranteed that all transactions have a GTID
          (except transactions generated in step 5 or earlier, which
          have already been processed). To start using the GTID protocol
          so that you can later perform automatic fail-over, execute the
          following on each slave. Optionally, if you use multi-source
          replication, do this for each channel and include the
          <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause:
        </p><pre data-lang="sql" class="programlisting">STOP SLAVE [FOR CHANNEL 'channel'];
CHANGE MASTER TO MASTER_AUTO_POSITION = 1 [FOR CHANNEL 'channel'];
START SLAVE [FOR CHANNEL 'channel'];</pre></li></ol>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-mode-change-online-disable-gtids"></a>17.1.5.3 Disabling GTID Transactions Online</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270455024"></a><p>
      This section describes how to disable GTID transactions on servers
      that are already online. This procedure does not require taking
      the server offline and is suited to use in production. However, if
      you have the possibility to take the servers offline when
      disabling GTIDs mode that process is easier.
    </p><p>
      The process is similar to enabling GTID transactions while the
      server is online, but reversing the steps. The only thing that
      differs is the point at which you wait for logged transactions to
      replicate.
    </p><p>
      Before you start, ensure that the servers meet the following
      pre-conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <span class="emphasis"><em>All</em></span> servers in your topology must use
          MySQL 5.7.6 or later. You cannot disable GTID transactions
          online on any single server unless <span class="emphasis"><em>all</em></span>
          servers which are in the topology are using this version.
        </p></li><li class="listitem"><p>
          All servers have <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
          set to <code class="literal">ON</code>.
        </p></li><li class="listitem"><p>
          The <a class="link" href="replication.html#option_mysqld_replicate-same-server-id"><code class="option">--replicate-same-server-id</code></a>
          option is not set on any server. You cannot disable GTID
          transactions if this option is set together with the
          <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a> option
          (which is the default) and binary logging is enabled (which is
          also the default). Without GTIDs, this combination of options
          causes infinite loops in circular replication.
</p></li></ul>
</div>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Execute the following on each slave, and if you using
          multi-source replication, do it for each channel and include
          the <code class="literal">FOR CHANNEL</code> channel clause:
        </p><pre data-lang="sql" class="programlisting">STOP SLAVE [FOR CHANNEL 'channel'];
CHANGE MASTER TO MASTER_AUTO_POSITION = 0, MASTER_LOG_FILE = file, \
MASTER_LOG_POS = position [FOR CHANNEL 'channel'];
START SLAVE [FOR CHANNEL 'channel'];
 </pre></li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = ON_PERMISSIVE;</pre></li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = OFF_PERMISSIVE;</pre></li><li class="listitem"><p>
          On each server, wait until the variable @@GLOBAL.GTID_OWNED is
          equal to the empty string. This can be checked using:
        </p><pre data-lang="sql" class="programlisting">SELECT @@GLOBAL.GTID_OWNED;</pre><p>
          On a replication slave, it is theoretically possible that this
          is empty and then nonempty again. This is not a problem, it
          suffices that it is empty once.
        </p></li><li class="listitem"><p>
          Wait for all transactions that currently exist in any binary
          log to replicate to all slaves. See
          <a class="xref" href="replication.html#replication-mode-change-online-verify-transactions" title="17.1.5.4 Verifying Replication of Anonymous Transactions">Section 17.1.5.4, “Verifying Replication of Anonymous Transactions”</a>
          for one method of checking that all anonymous transactions
          have replicated to all servers.
        </p></li><li class="listitem"><p>
          If you use binary logs for anything else than replication, for
          example to do point in time backup or restore: wait until you
          do not need the old binary logs having GTID transactions.
        </p><p>
          For instance, after step 5 has completed, you can execute
          <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH LOGS</code></a> on the server where
          you are taking the backup. Then either explicitly take a
          backup or wait for the next iteration of any periodic backup
          routine you may have set up.
        </p><p>
          Ideally, wait for the server to purge all binary logs that
          existed when step 5 was completed. Also wait for any backup
          taken before step 5 to expire.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
            This is the one important point during this procedure. It is
            important to understand that logs containing GTID
            transactions cannot be used after the next step. Before
            proceeding you must be sure that GTID transactions do not
            exist anywhere in the topology.
</p>
</div>
</li><li class="listitem"><p>
          On each server, execute:
        </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.GTID_MODE = OFF;</pre></li><li class="listitem"><p>
          On each server, set
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=OFF</code></a> in
          <code class="filename">my.cnf</code>.
        </p><p>
          If you want to set
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency=OFF</code></a>,
          you can do so now. After setting it, you should add
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency=OFF</code></a>
          to your configuration file.
</p></li></ol>
</div>
<p>
      If you want to downgrade to an earlier version of MySQL, you can
      do so now, using the normal downgrade procedure.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-mode-change-online-verify-transactions"></a>17.1.5.4 Verifying Replication of Anonymous Transactions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444270418048"></a><p>
      This section explains how to monitor a replication topology and
      verify that all anonymous transactions have been replicated. This
      is helpful when changing the replication mode online as you can
      verify that it is safe to change to GTID transactions.
    </p><p>
      There are several possible ways to wait for transactions to
      replicate:
    </p><p>
      The simplest method, which works regardless of your topology but
      relies on timing is as follows: if you are sure that the slave
      never lags more than N seconds, just wait for a bit more than N
      seconds. Or wait for a day, or whatever time period you consider
      safe for your deployment.
    </p><p>
      A safer method in the sense that it does not depend on timing: if
      you only have a master with one or more slaves, do the following:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          On the master, execute:
        </p><pre data-lang="sql" class="programlisting">SHOW MASTER STATUS;</pre><p>
          Note down the values in the <code class="literal">File</code> and
          <code class="literal">Position</code> column.
        </p></li><li class="listitem"><p>
          On every slave, use the file and position information from the
          master to execute:
</p><pre data-lang="sql" class="programlisting">SELECT MASTER_POS_WAIT(file, position);</pre></li></ol>
</div>
<p>
      If you have a master and multiple levels of slaves, or in other
      words you have slaves of slaves, repeat step 2 on each level,
      starting from the master, then all the direct slaves, then all the
      slaves of slaves, and so on.
    </p><p>
      If you use a circular replication topology where multiple servers
      may have write clients, perform step 2 for each master-slave
      connection, until you have completed the full circle. Repeat the
      whole process so that you do the full circle
      <span class="emphasis"><em>twice</em></span>.
    </p><p>
      For example, suppose you have three servers A, B, and C,
      replicating in a circle so that A -&gt; B -&gt; C -&gt; A. The
      procedure is then:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Do step 1 on A and step 2 on B.
        </p></li><li class="listitem"><p>
          Do step 1 on B and step 2 on C.
        </p></li><li class="listitem"><p>
          Do step 1 on C and step 2 on A.
        </p></li><li class="listitem"><p>
          Do step 1 on A and step 2 on B.
        </p></li><li class="listitem"><p>
          Do step 1 on B and step 2 on C.
        </p></li><li class="listitem"><p>
          Do step 1 on C and step 2 on A.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-options"></a>17.1.6 Replication and Binary Logging Options and Variables</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-options-reference">17.1.6.1 Replication and Binary Logging Option and Variable Reference</a></span></dt><dt><span class="section"><a href="replication.html#replication-options-master">17.1.6.2 Replication Master Options and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-options-slave">17.1.6.3 Replication Slave Options and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-options-binary-log">17.1.6.4 Binary Logging Options and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-options-gtids">17.1.6.5 Global Transaction ID System Variables</a></span></dt></dl>
</div>
<p>
    The following sections contain information about
    <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> options and server variables that are used
    in replication and for controlling the binary log. Options and
    variables for use on replication masters and replication slaves are
    covered separately, as are options and variables relating to binary
    logging and global transaction identifiers (GTIDs). A set of
    quick-reference tables providing basic information about these
    options and variables is also included.
  </p><p><a name="sysvar_server_id"></a>
    Of particular importance is the
    <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable.
</p><a class="indexterm" name="idm46444270394336"></a><a class="indexterm" name="idm46444270393248"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for server_id"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--server-id=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_server_id">server_id</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
    This variable specifies the server ID.
    <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> is set to 1 by default.
    The server can be started with this default ID, but when binary
    logging is enabled, an informational message is issued if you did
    not set <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> explicitly to
    specify a server ID.
  </p><p>
    For servers that are used in a replication topology, you must
    specify a unique server ID for each replication server, in the range
    from 1 to 2<sup>32</sup> − 1.
    <span class="quote">“<span class="quote">Unique</span>”</span> means that each ID must be different from
    every other ID in use by any other replication master or slave. For
    additional information, see
    <a class="xref" href="replication.html#replication-options-master" title="17.1.6.2 Replication Master Options and Variables">Section 17.1.6.2, “Replication Master Options and Variables”</a>, and
    <a class="xref" href="replication.html#replication-options-slave" title="17.1.6.3 Replication Slave Options and Variables">Section 17.1.6.3, “Replication Slave Options and Variables”</a>.
  </p><p>
    If the server ID is set to 0, binary logging takes place, but a
    master with a server ID of 0 refuses any connections from slaves,
    and a slave with a server ID of 0 refuses to connect to a master.
    Note that although you can change the server ID dynamically to a
    nonzero value, doing so does not enable replication to start
    immediately. You must change the server ID and then restart the
    server to initialize the replication slave.
  </p><p>
    For more information, see
    <a class="xref" href="replication.html#replication-howto-slavebaseconfig" title="17.1.2.2 Setting the Replication Slave Configuration">Section 17.1.2.2, “Setting the Replication Slave Configuration”</a>.
  </p><p><a name="sysvar_server_uuid"></a>
    <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a>
  </p><a class="indexterm" name="idm46444270347920"></a><a class="indexterm" name="idm46444270346416"></a><p>
    The MySQL server generates a true UUID in addition to the default or
    user-supplied server ID set in the <code class="literal">server_id</code>
    system variable. This is available as the global, read-only variable
    <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      The presence of the <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a>
      system variable does not change the requirement for setting a
      unique <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> value for each
      MySQL server as part of preparing and running MySQL replication,
      as described earlier in this section.
</p>
</div>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for server_uuid"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_server_uuid">server_uuid</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
    When starting, the MySQL server automatically obtains a UUID as
    follows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
        <a class="indexterm" name="idm46444270315872"></a>

        Attempt to read and use the UUID written in the file
        <code class="filename"><em class="replaceable"><code>data_dir</code></em>/auto.cnf</code>
        (where <em class="replaceable"><code>data_dir</code></em> is the server's
        data directory).
      </p></li><li class="listitem"><p>
        If
        <code class="filename"><em class="replaceable"><code>data_dir</code></em>/auto.cnf</code>
        is not found, generate a new UUID and save it to this file,
        creating the file if necessary.
</p></li></ol>
</div>
<p>
    The <code class="filename">auto.cnf</code> file has a format similar to that
    used for <code class="filename">my.cnf</code> or <code class="filename">my.ini</code>
    files. <code class="filename">auto.cnf</code> has only a single
    <code class="literal">[auto]</code> section containing a single
    <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> setting and value; the
    file's contents appear similar to what is shown here:
  </p><pre data-lang="ini" class="programlisting">[auto]
server_uuid=8a94f357-aab4-11df-86ab-c80aa9429562</pre>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
      The <code class="filename">auto.cnf</code> file is automatically generated;
      do not attempt to write or modify this file.
</p>
</div>
<p>
    When using MySQL replication, masters and slaves know each
    other's UUIDs. The value of a slave's UUID can be seen in
    the output of <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE HOSTS</code></a>. Once
    <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> has been executed, the
    value of the master's UUID is available on the slave in the
    output of <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      Issuing a <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> or
      <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> statement does
      <span class="emphasis"><em>not</em></span> reset the master's UUID as used on
      the slave.
</p>
</div>
<p>
    A server's <code class="literal">server_uuid</code> is also used in GTIDs
    for transactions originating on that server. For more information,
    see <a class="xref" href="replication.html#replication-gtids" title="17.1.3 Replication with Global Transaction Identifiers">Section 17.1.3, “Replication with Global Transaction Identifiers”</a>.
  </p><p>
    When starting, the slave I/O thread generates an error and aborts if
    its master's UUID is equal to its own unless the
    <a class="link" href="replication.html#option_mysqld_replicate-same-server-id"><code class="option">--replicate-same-server-id</code></a> option has
    been set. In addition, the slave I/O thread generates a warning if
    either of the following is true:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        No master having the expected
        <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> exists.
      </p></li><li class="listitem"><p>
        The master's <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a>
        has changed, although no <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
        TO</code></a> statement has ever been executed.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-options-reference"></a>17.1.6.1 Replication and Binary Logging Option and Variable Reference</h4>

</div>

</div>

</div>
<p>
      The following two sections provide basic information about the
      MySQL command-line options and system variables applicable to
      replication and the binary log.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-optvars-list"></a>Replication Options and Variables</h5>
</div>
</div>
</div>
<p>
    The command-line options and system variables in the following list
    relate to replication masters and replication slaves.
    <a class="xref" href="replication.html#replication-options-master" title="17.1.6.2 Replication Master Options and Variables">Section 17.1.6.2, “Replication Master Options and Variables”</a>, provides more detailed
    information about options and variables relating to replication
    master servers. For more information about options and variables
    relating to replication slaves, see
    <a class="xref" href="replication.html#replication-options-slave" title="17.1.6.3 Replication Slave Options and Variables">Section 17.1.6.3, “Replication Slave Options and Variables”</a>.
</p>
<div class="itemizedlist">
<a name="replication-optvar-summary-list"></a><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_abort-slave-event-count">abort-slave-event-count</a></code>:
        Option used by mysql-test for debugging and testing of
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_auto_increment_increment">auto_increment_increment</a></code>:
        AUTO_INCREMENT columns are incremented by this value.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_auto_increment_offset">auto_increment_offset</a></code>:
        Offset added to AUTO_INCREMENT columns.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds">binlog_expire_logs_seconds</a></code>:
        Purge binary logs after this many seconds.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery">binlog_gtid_simple_recovery</a></code>:
        Controls how binary logs are iterated during GTID recovery.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_change_master</a></code>:
        Count of CHANGE MASTER TO statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_show_master_status</a></code>:
        Count of SHOW MASTER STATUS statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_show_slave_hosts</a></code>:
        Count of SHOW SLAVE HOSTS statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_show_slave_status</a></code>:
        Count of SHOW SLAVE STATUS statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_slave_start</a></code>:
        Count of START SLAVE statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_slave_stop</a></code>:
        Count of STOP SLAVE statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_disconnect-slave-event-count">disconnect-slave-event-count</a></code>:
        Option used by mysql-test for debugging and testing of
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_enforce_gtid_consistency">enforce_gtid_consistency</a></code>:
        Prevents execution of statements that cannot be logged in a
        transactionally safe manner.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_expire_logs_days">expire_logs_days</a></code>:
        Purge binary logs after this many days.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_executed">gtid_executed</a></code>:
        Global: All GTIDs in the binary log (global) or current
        transaction (session). Read-only.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_executed_compression_period">gtid_executed_compression_period</a></code>:
        Compress gtid_executed table each time this many transactions
        have occurred. 0 means never compress this table. Applies only
        when binary logging is disabled.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_mode">gtid_mode</a></code>:
        Controls whether GTID based logging is enabled and what type of
        transactions the logs can contain.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_next">gtid_next</a></code>:
        Specifies the GTID for the next statement to execute; see
        documentation for details.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_owned">gtid_owned</a></code>:
        The set of GTIDs owned by this client (session), or by all
        clients, together with the thread ID of the owner (global).
        Read-only.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_gtid_purged">gtid_purged</a></code>:
        The set of all GTIDs that have been purged from the binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_init_slave">init_slave</a></code>:
        Statements that are executed when a slave connects to a master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_bin_trust_function_creators">log_bin_trust_function_creators</a></code>:
        If equal to 0 (the default), then when --log-bin is used,
        creation of a stored function is allowed only to users having
        the SUPER privilege and only if the function created does not
        break binary logging.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_statements_unsafe_for_binlog">log_statements_unsafe_for_binlog</a></code>:
        Disables error 1592 warnings being written to the error log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_master-info-file">master-info-file</a></code>:
        The location and name of the file that remembers the master and
        where the I/O replication thread is in the master's binary logs.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_master-retry-count">master-retry-count</a></code>:
        Number of tries the slave makes to connect to the master before
        giving up.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_master_info_repository">master_info_repository</a></code>:
        Whether to write master status information and replication I/O
        thread location in the master's binary logs to a file or table.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_max_relay_log_size">max_relay_log_size</a></code>:
        If nonzero, relay log is rotated automatically when its size
        exceeds this value. If zero, size at which rotation occurs is
        determined by the value of max_binlog_size.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_original_commit_timestamp">original_commit_timestamp</a></code>:
        The time when a transaction was committed on the original
        master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_immediate_server_version">immediate_server_version</a></code>:
        The MySQL Server release number of the server that is the
        immediate master in a replication topology.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_original_server_version">original_server_version</a></code>:
        The MySQL Server release number of the server where a
        transaction was originally committed.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log">relay_log</a></code>:
        The location and base name to use for relay logs.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_basename">relay_log_basename</a></code>:
        Complete path to relay log, including file name.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_index">relay_log_index</a></code>:
        The location and name to use for the file that keeps a list of
        the last relay logs.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_info_file">relay_log_info_file</a></code>:
        File in which the slave records information about the relay
        logs.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_info_repository">relay_log_info_repository</a></code>:
        Whether to write the replication SQL thread's location in the
        relay logs to a file or a table.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_purge">relay_log_purge</a></code>:
        Determines whether relay logs are purged.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_recovery">relay_log_recovery</a></code>:
        Whether automatic recovery of relay log files from master at
        startup is enabled; must be enabled for a crash-safe slave.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_relay_log_space_limit">relay_log_space_limit</a></code>:
        Maximum space to use for all relay logs.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-do-db">replicate-do-db</a></code>:
        Tells the slave SQL thread to restrict replication to the
        specified database.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-do-table">replicate-do-table</a></code>:
        Tells the slave SQL thread to restrict replication to the
        specified table.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-ignore-db">replicate-ignore-db</a></code>:
        Tells the slave SQL thread not to replicate to the specified
        database.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-ignore-table">replicate-ignore-table</a></code>:
        Tells the slave SQL thread not to replicate to the specified
        table.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-rewrite-db">replicate-rewrite-db</a></code>:
        Updates to a database with a different name than the original.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-same-server-id">replicate-same-server-id</a></code>:
        In replication, if enabled, do not skip events having our server
        id.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-wild-do-table">replicate-wild-do-table</a></code>:
        Tells the slave thread to restrict replication to the tables
        that match the specified wildcard pattern.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table">replicate-wild-ignore-table</a></code>:
        Tells the slave thread not to replicate to the tables that match
        the given wildcard pattern.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_report_host">report_host</a></code>:
        Host name or IP of the slave to be reported to the master during
        slave registration.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_report_password">report_password</a></code>:
        An arbitrary password that the slave server should report to the
        master. Not the same as the password for the MySQL replication
        user account.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_report_port">report_port</a></code>:
        Port for connecting to slave reported to the master during slave
        registration.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_report_user">report_user</a></code>:
        An arbitrary user name that a slave server should report to the
        master. Not the same as the name used with the MySQL replication
        user account.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_clients">Rpl_semi_sync_master_clients</a></code>:
        Number of semisynchronous slaves.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled">rpl_semi_sync_master_enabled</a></code>:
        Whether semisynchronous replication is enabled on the master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_net_avg_wait_time">Rpl_semi_sync_master_net_avg_wait_time</a></code>:
        The average time the master waited for a slave reply.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_net_wait_time">Rpl_semi_sync_master_net_wait_time</a></code>:
        The total time the master waited for slave replies.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_net_waits">Rpl_semi_sync_master_net_waits</a></code>:
        The total number of times the master waited for slave replies.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_no_times">Rpl_semi_sync_master_no_times</a></code>:
        Number of times the master turned off semisynchronous
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_no_tx">Rpl_semi_sync_master_no_tx</a></code>:
        Number of commits not acknowledged successfully.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_status">Rpl_semi_sync_master_status</a></code>:
        Whether semisynchronous replication is operational on the
        master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_timefunc_failures">Rpl_semi_sync_master_timefunc_failures</a></code>:
        Number of times the master failed when calling time functions.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout">rpl_semi_sync_master_timeout</a></code>:
        Number of milliseconds to wait for slave acknowledgment.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_trace_level">rpl_semi_sync_master_trace_level</a></code>:
        The semisynchronous replication debug trace level on the master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_tx_avg_wait_time">Rpl_semi_sync_master_tx_avg_wait_time</a></code>:
        The average time the master waited for each transaction.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_tx_wait_time">Rpl_semi_sync_master_tx_wait_time</a></code>:
        The total time the master waited for transactions.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_tx_waits">Rpl_semi_sync_master_tx_waits</a></code>:
        The total number of times the master waited for transactions.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count">rpl_semi_sync_master_wait_for_slave_count</a></code>:
        How many slave acknowledgments the master must receive per
        transaction before proceeding.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_no_slave">rpl_semi_sync_master_wait_no_slave</a></code>:
        Whether master waits for timeout even with no slaves.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_point">rpl_semi_sync_master_wait_point</a></code>:
        The wait point for slave transaction receipt acknowledgment.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_wait_pos_backtraverse">Rpl_semi_sync_master_wait_pos_backtraverse</a></code>:
        The total number of times the master waited for an event with
        binary coordinates lower than events waited for previously.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_wait_sessions">Rpl_semi_sync_master_wait_sessions</a></code>:
        Number of sessions currently waiting for slave replies.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_yes_tx">Rpl_semi_sync_master_yes_tx</a></code>:
        Number of commits acknowledged successfully.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_enabled">rpl_semi_sync_slave_enabled</a></code>:
        Whether semisynchronous replication is enabled on slave.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Rpl_semi_sync_slave_status">Rpl_semi_sync_slave_status</a></code>:
        Whether semisynchronous replication is operational on slave.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_trace_level">rpl_semi_sync_slave_trace_level</a></code>:
        The semisynchronous replication debug trace level on the slave.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_read_size">rpl_read_size</a></code>:
        Set the minimum amount of data in bytes that is read from the
        binary log files and relay log files.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_rpl_stop_slave_timeout">rpl_stop_slave_timeout</a></code>:
        Set the number of seconds that STOP SLAVE waits before timing
        out.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_server_uuid">server_uuid</a></code>:
        The server's globally unique ID, automatically (re)generated at
        server start.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_show-slave-auth-info">show-slave-auth-info</a></code>:
        Show user name and password in SHOW SLAVE HOSTS on this master.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_skip-slave-start">skip-slave-start</a></code>:
        If set, slave is not autostarted.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_load_tmpdir">slave_load_tmpdir</a></code>:
        The location where the slave should put its temporary files when
        replicating LOAD DATA statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_net_timeout">slave_net_timeout</a></code>:
        Number of seconds to wait for more data from a master/slave
        connection before aborting the read.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_slave-skip-errors">slave-skip-errors</a></code>:
        Tells the slave thread to continue replication when a query
        returns an error from the provided list.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_checkpoint_group">slave_checkpoint_group</a></code>:
        Maximum number of transactions processed by a multithreaded
        slave before a checkpoint operation is called to update progress
        status. Not supported by NDB Cluster.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_checkpoint_period">slave_checkpoint_period</a></code>:
        Update progress status of multithreaded slave and flush relay
        log info to disk after this number of milliseconds. Not
        supported by NDB Cluster.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_compressed_protocol">slave_compressed_protocol</a></code>:
        Use compression of master/slave protocol.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_exec_mode">slave_exec_mode</a></code>:
        Allows for switching the slave thread between IDEMPOTENT mode
        (key and some other errors suppressed) and STRICT mode; STRICT
        mode is the default, except for NDB Cluster, where IDEMPOTENT is
        always used.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_max_allowed_packet">slave_max_allowed_packet</a></code>:
        Maximum size, in bytes, of a packet that can be sent from a
        replication master to a slave; overrides max_allowed_packet.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Slave_open_temp_tables">Slave_open_temp_tables</a></code>:
        Number of temporary tables that the slave SQL thread currently
        has open.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_parallel_type">slave_parallel_type</a></code>:
        Tells the slave to use timestamp information (LOGICAL_CLOCK) or
        database partioning (DATABASE) to parallelize transactions.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_parallel_workers">slave_parallel_workers</a></code>:
        Number of applier threads for executing replication transactions
        in parallel. A value of 0 disables slave multithreading. Not
        supported by MySQL Cluster.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max">slave_pending_jobs_size_max</a></code>:
        Maximum size of slave worker queues holding events not yet
        applied.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_preserve_commit_order">slave_preserve_commit_order</a></code>:
        Ensures that all commits by slave workers happen in the same
        order as on the master to maintain consistency when using
        parallel applier threads.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_rows_search_algorithms">slave_rows_search_algorithms</a></code>:
        Determines search algorithms used for slave update batching. Any
        2 or 3 from the list INDEX_SEARCH, TABLE_SCAN, HASH_SCAN.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Slave_rows_last_search_algorithm_used">Slave_rows_last_search_algorithm_used</a></code>:
        Search algorithm most recently used by this slave to locate rows
        for row-based replication (index, table, or hash scan).
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_transaction_retries">slave_transaction_retries</a></code>:
        Number of times the slave SQL thread will retry a transaction in
        case it failed with a deadlock or elapsed lock wait timeout,
        before giving up and stopping.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_type_conversions">slave_type_conversions</a></code>:
        Controls type conversion mode on replication slave. Value is a
        list of zero or more elements from the list: ALL_LOSSY,
        ALL_NON_LOSSY. Set to an empty string to disallow type
        conversions between master and slave.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sql_log_bin">sql_log_bin</a></code>:
        Controls binary logging for the current session.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sql_slave_skip_counter">sql_slave_skip_counter</a></code>:
        Number of events from the master that a slave server should
        skip. Not compatible with GTID replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sync_master_info">sync_master_info</a></code>:
        Synchronize master.info to disk after every #th event.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sync_relay_log">sync_relay_log</a></code>:
        Synchronize relay log to disk after every #th event.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sync_relay_log_info">sync_relay_log_info</a></code>:
        Synchronize relay.info file to disk after every #th event.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_transaction_write_set_extraction">transaction_write_set_extraction</a></code>:
        Defines the algorithm used to hash the writes extracted during a
        transaction.
</p></li></ul>
</div>
<p>
    For a listing of all command-line options, system and status
    variables used with <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>, see
    <a class="xref" href="server-administration.html#server-option-variable-reference" title="5.1.4 Server Option, System Variable, and Status Variable Reference">Section 5.1.4, “Server Option, System Variable, and Status Variable Reference”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="binlog-optvars-list"></a>Binary Logging Options and Variables</h5>

</div>

</div>

</div>
<p>
    The command-line options and system variables in the following list
    relate to the binary log.
    <a class="xref" href="replication.html#replication-options-binary-log" title="17.1.6.4 Binary Logging Options and Variables">Section 17.1.6.4, “Binary Logging Options and Variables”</a>, provides more
    detailed information about options and variables relating to binary
    logging. For additional general information about the binary log,
    see <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
</p>
<div class="itemizedlist">
<a name="binlog-optvar-summary-list"></a><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_binlog-checksum">binlog-checksum</a></code>:
        Enable/disable binary log checksums.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_binlog-do-db">binlog-do-db</a></code>:
        Limits binary logging to specific databases.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_format">binlog_format</a></code>:
        Specifies the format of the binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_binlog-ignore-db">binlog-ignore-db</a></code>:
        Tells the master that updates to the given database should not
        be logged to the binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_binlog-row-event-max-size">binlog-row-event-max-size</a></code>:
        Binary log max event size.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_encryption">binlog_encryption</a></code>:
        Enable encryption for binary log files and relay log files on
        this server.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup">binlog_rotate_encryption_master_key_at_startup</a></code>:
        Rotate the binary log master key at server startup.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Binlog_cache_disk_use">Binlog_cache_disk_use</a></code>:
        Number of transactions that used a temporary file instead of the
        binary log cache.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_cache_size">binlog_cache_size</a></code>:
        Size of the cache to hold the SQL statements for the binary log
        during a transaction.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Binlog_cache_use">Binlog_cache_use</a></code>:
        Number of transactions that used the temporary binary log cache.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_checksum">binlog_checksum</a></code>:
        Enable/disable binary log checksums.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates">binlog_direct_non_transactional_updates</a></code>:
        Causes updates using statement format to nontransactional
        engines to be written directly to binary log. See documentation
        before using.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_error_action">binlog_error_action</a></code>:
        Controls what happens when the server cannot write to the binary
        log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay">binlog_group_commit_sync_delay</a></code>:
        Sets the number of microseconds to wait before synchronizing
        transactions to disk.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_group_commit_sync_no_delay_count">binlog_group_commit_sync_no_delay_count</a></code>:
        Sets the maximum number of transactions to wait for before
        aborting the current delay specified by
        binlog_group_commit_sync_delay.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_max_flush_queue_time">binlog_max_flush_queue_time</a></code>:
        How long to read transactions before flushing to binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_order_commits">binlog_order_commits</a></code>:
        Whether to commit in same order as writes to binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_image">binlog_row_image</a></code>:
        Use full or minimal images when logging row changes.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_metadata">binlog_row_metadata</a></code>:
        Configures the amount of table related metadata binary logged
        when using row-based logging.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_value_options">binlog_row_value_options</a></code>:
        Enables binary logging of partial JSON updates for row-based
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_rows_query_log_events">binlog_rows_query_log_events</a></code>:
        When enabled, enables logging of rows query log events when
        using row-based logging. Disabled by default. Do not enable when
        producing logs for pre-5.6 slaves/readers.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Binlog_stmt_cache_disk_use">Binlog_stmt_cache_disk_use</a></code>:
        Number of nontransactional statements that used a temporary file
        instead of the binary log statement cache.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_stmt_cache_size">binlog_stmt_cache_size</a></code>:
        Size of the cache to hold nontransactional statements for the
        binary log during a transaction.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Binlog_stmt_cache_use">Binlog_stmt_cache_use</a></code>:
        Number of statements that used the temporary binary log
        statement cache.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_compression">binlog_transaction_compression</a></code>:
        Enable compression for transaction payloads in binary log files.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_compression_level_zstd">binlog_transaction_compression_level_zstd</a></code>:
        Compression level for transaction payloads in binary log files.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking">binlog_transaction_dependency_tracking</a></code>:
        Source of dependency information (commit timestamps or
        transaction write sets) from which to assess which transactions
        can be executed in parallel by slave's multithreaded applier.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_dependency_history_size">binlog_transaction_dependency_history_size</a></code>:
        Number of row hashes kept for looking up transaction that last
        updated some row.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_show_binlog_events</a></code>:
        Count of SHOW BINLOG EVENTS statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="server-administration.html#statvar_Com_xxx">Com_show_binlogs</a></code>:
        Count of SHOW BINLOGS statements.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_log-bin">log-bin</a></code>:
        Specifies the base name for binary log files.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_log-bin-index">log-bin-index</a></code>:
        Specifies the name for the binary log index file.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_bin">log_bin</a></code>:
        Whether the binary log is enabled.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_bin_basename">log_bin_basename</a></code>:
        Path and base name for binary log files.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_bin_use_v1_row_events">log_bin_use_v1_row_events</a></code>:
        Whether server is using version 1 binary log row events.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_log_slave_updates">log_slave_updates</a></code>:
        Whether the slave should log the updates performed by its SQL
        thread to its own binary log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_master_verify_checksum">master_verify_checksum</a></code>:
        Cause master to examine checksums when reading from the binary
        log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_max-binlog-dump-events">max-binlog-dump-events</a></code>:
        Option used by mysql-test for debugging and testing of
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_cache_size">max_binlog_cache_size</a></code>:
        Can be used to restrict the total size used to cache a
        multi-statement transaction.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_size">max_binlog_size</a></code>:
        Binary log will be rotated automatically when size exceeds this
        value.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_stmt_cache_size">max_binlog_stmt_cache_size</a></code>:
        Can be used to restrict the total size used to cache all
        nontransactional statements during a transaction.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_slave-sql-verify-checksum">slave-sql-verify-checksum</a></code>:
        Cause slave to examine checksums when reading from the relay
        log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_slave_sql_verify_checksum">slave_sql_verify_checksum</a></code>:
        Cause slave to examine checksums when reading from relay log.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#option_mysqld_sporadic-binlog-dump-fail">sporadic-binlog-dump-fail</a></code>:
        Option used by mysql-test for debugging and testing of
        replication.
      </p></li><li class="listitem"><p>
        <code class="literal"><a class="link" href="replication.html#sysvar_sync_binlog">sync_binlog</a></code>:
        Synchronously flush binary log to disk after every #th event.
</p></li></ul>
</div>
<p>
    For a listing of all command-line options, system and status
    variables used with <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>, see
    <a class="xref" href="server-administration.html#server-option-variable-reference" title="5.1.4 Server Option, System Variable, and Status Variable Reference">Section 5.1.4, “Server Option, System Variable, and Status Variable Reference”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-options-master"></a>17.1.6.2 Replication Master Options and Variables</h4>

</div>

</div>

</div>
<p>
      This section describes the server options and system variables
      that you can use on replication master servers. You can specify
      the options either on the
      <a class="link" href="programs.html#command-line-options" title="4.2.2.1 Using Options on the Command Line">command line</a> or in an
      <a class="link" href="programs.html#option-files" title="4.2.2.2 Using Option Files">option file</a>. You can specify
      system variable values using
      <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>.
    </p><p>
      On the master and each slave, you must set the
      <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable to
      establish a unique replication ID. For each server, you should
      pick a unique positive integer in the range from 1 to
      2<sup>32</sup> − 1, and each ID must be
      different from every other ID in use by any other replication
      master or slave. Example: <code class="literal">server-id=3</code>.
    </p><p>
      For options used on the master for controlling binary logging, see
      <a class="xref" href="replication.html#replication-options-binary-log" title="17.1.6.4 Binary Logging Options and Variables">Section 17.1.6.4, “Binary Logging Options and Variables”</a>.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-optvars-masters"></a>Startup Options for Replication Masters</h5>
</div>
</div>
</div>
<p>
        The following list describes startup options for controlling
        replication master servers. Replication-related system variables
        are discussed later in this section.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_show-slave-auth-info"></a>
            <a class="indexterm" name="idm46444269948416"></a>

            <a class="indexterm" name="idm46444269946960"></a>

            <a class="link" href="replication.html#option_mysqld_show-slave-auth-info"><code class="option">--show-slave-auth-info</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for show-slave-auth-info"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--show-slave-auth-info[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Display slave user names and passwords in the output of
            <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE HOSTS</code></a> on the
            master server for slaves started with the
            <a class="link" href="replication.html#sysvar_report_user"><code class="option">--report-user</code></a> and
            <a class="link" href="replication.html#sysvar_report_password"><code class="option">--report-password</code></a> options.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-sysvars-masters"></a>System Variables Used on Replication Masters</h5>

</div>

</div>

</div>
<p>
        The following system variables are used for or by replication
        masters:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="sysvar_auto_increment_increment"></a>
            <a class="indexterm" name="idm46444269922528"></a>

            <a class="indexterm" name="idm46444269921424"></a>

            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for auto_increment_increment"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--auto-increment-increment=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_auto_increment_increment">auto_increment_increment</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">65535</code></td>
</tr></tbody></table>
</div>
<p>
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
            and <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
            are intended for use with master-to-master replication, and
            can be used to control the operation of
            <code class="literal">AUTO_INCREMENT</code> columns. Both variables
            have global and session values, and each can assume an
            integer value between 1 and 65,535 inclusive. Setting the
            value of either of these two variables to 0 causes its value
            to be set to 1 instead. Attempting to set the value of
            either of these two variables to an integer greater than
            65,535 or less than 0 causes its value to be set to 65,535
            instead. Attempting to set the value of
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a> or
            <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a> to a
            noninteger value produces an error, and the actual value of
            the variable remains unchanged.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
              is also supported for use with
              <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a> tables.
</p>
</div>
<p>
            As of MySQL 8.0.18, setting the session value of this system
            variable is no longer a restricted operation.
          </p><p>
            When Group Replication is started on a server, the value of
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a> is
            changed to the value of
            <a class="link" href="group-replication.html#sysvar_group_replication_auto_increment_increment"><code class="literal">group_replication_auto_increment_increment</code></a>,
            which defaults to 7, and the value of
            <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a> is
            changed to the server ID. The changes are reverted when
            Group Replication is stopped. These changes are only made
            and reverted if
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
            and <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
            each have their default value of 1. If their values have
            already been modified from the default, Group Replication
            does not alter them. From MySQL 8.0, the system variables
            are also not modified when Group Replication is in
            single-primary mode, where only one server writes.
          </p><p>
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
            and <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
            affect <code class="literal">AUTO_INCREMENT</code> column behavior as
            follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
                controls the interval between successive column values.
                For example:
              </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'auto_inc%';</code></strong>
+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| auto_increment_increment | 1     |
| auto_increment_offset    | 1     |
+--------------------------+-------+
2 rows in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>CREATE TABLE autoinc1</code></strong>
    -&gt; <strong class="userinput"><code>(col INT NOT NULL AUTO_INCREMENT PRIMARY KEY);</code></strong>
  Query OK, 0 rows affected (0.04 sec)

mysql&gt; <strong class="userinput"><code>SET @@auto_increment_increment=10;</code></strong>
Query OK, 0 rows affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'auto_inc%';</code></strong>
+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| auto_increment_increment | 10    |
| auto_increment_offset    | 1     |
+--------------------------+-------+
2 rows in set (0.01 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);</code></strong>
Query OK, 4 rows affected (0.00 sec)
Records: 4  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT col FROM autoinc1;</code></strong>
+-----+
| col |
+-----+
|   1 |
|  11 |
|  21 |
|  31 |
+-----+
4 rows in set (0.00 sec)
</pre></li><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
                determines the starting point for the
                <code class="literal">AUTO_INCREMENT</code> column value. Consider
                the following, assuming that these statements are
                executed during the same session as the example given in
                the description for
                <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>:
              </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET @@auto_increment_offset=5;</code></strong>
Query OK, 0 rows affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'auto_inc%';</code></strong>
+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| auto_increment_increment | 10    |
| auto_increment_offset    | 5     |
+--------------------------+-------+
2 rows in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>CREATE TABLE autoinc2</code></strong>
    -&gt; <strong class="userinput"><code>(col INT NOT NULL AUTO_INCREMENT PRIMARY KEY);</code></strong>
Query OK, 0 rows affected (0.06 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO autoinc2 VALUES (NULL), (NULL), (NULL), (NULL);</code></strong>
Query OK, 4 rows affected (0.00 sec)
Records: 4  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT col FROM autoinc2;</code></strong>
+-----+
| col |
+-----+
|   5 |
|  15 |
|  25 |
|  35 |
+-----+
4 rows in set (0.02 sec)
</pre><p>
                When the value of
                <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
                is greater than that of
                <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>,
                the value of
                <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
                is ignored.
</p></li></ul>
</div>
<p>
            If either of these variables is changed, and then new rows
            inserted into a table containing an
            <code class="literal">AUTO_INCREMENT</code> column, the results may
            seem counterintuitive because the series of
            <code class="literal">AUTO_INCREMENT</code> values is calculated
            without regard to any values already present in the column,
            and the next value inserted is the least value in the series
            that is greater than the maximum existing value in the
            <code class="literal">AUTO_INCREMENT</code> column. The series is
            calculated like this:
          </p><p>
            <code class="literal">auto_increment_offset</code> +
            <em class="replaceable"><code>N</code></em> ×
            <code class="literal">auto_increment_increment</code>
          </p><p>
            where <em class="replaceable"><code>N</code></em> is a positive integer
            value in the series [1, 2, 3, ...]. For example:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'auto_inc%';</code></strong>
+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| auto_increment_increment | 10    |
| auto_increment_offset    | 5     |
+--------------------------+-------+
2 rows in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT col FROM autoinc1;</code></strong>
+-----+
| col |
+-----+
|   1 |
|  11 |
|  21 |
|  31 |
+-----+
4 rows in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);</code></strong>
Query OK, 4 rows affected (0.00 sec)
Records: 4  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT col FROM autoinc1;</code></strong>
+-----+
| col |
+-----+
|   1 |
|  11 |
|  21 |
|  31 |
|  35 |
|  45 |
|  55 |
|  65 |
+-----+
8 rows in set (0.00 sec)
</pre><p>
            The values shown for
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
            and <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
            generate the series 5 + <em class="replaceable"><code>N</code></em> ×
            10, that is, [5, 15, 25, 35, 45, ...]. The highest value
            present in the <code class="literal">col</code> column prior to the
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> is 31, and the next
            available value in the <code class="literal">AUTO_INCREMENT</code>
            series is 35, so the inserted values for
            <code class="literal">col</code> begin at that point and the results
            are as shown for the <a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT</code></a>
            query.
          </p><p>
            It is not possible to restrict the effects of these two
            variables to a single table; these variables control the
            behavior of all <code class="literal">AUTO_INCREMENT</code> columns in
            <span class="emphasis"><em>all</em></span> tables on the MySQL server. If the
            global value of either variable is set, its effects persist
            until the global value is changed or overridden by setting
            the session value, or until <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> is
            restarted. If the local value is set, the new value affects
            <code class="literal">AUTO_INCREMENT</code> columns for all tables
            into which new rows are inserted by the current user for the
            duration of the session, unless the values are changed
            during that session.
          </p><p>
            The default value of
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a> is
            1. See
            <a class="xref" href="replication.html#replication-features-auto-increment" title="17.5.1.1 Replication and AUTO_INCREMENT">Section 17.5.1.1, “Replication and AUTO_INCREMENT”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_auto_increment_offset"></a>
            <a class="indexterm" name="idm46444269810960"></a>

            <a class="indexterm" name="idm46444269809920"></a>

            <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for auto_increment_offset"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--auto-increment-offset=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_auto_increment_offset">auto_increment_offset</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">65535</code></td>
</tr></tbody></table>
</div>
<p>
            This variable has a default value of 1. If it is left with
            its default value, and Group Replication is started on the
            server in multi-primary mode, it is changed to the server
            ID. For more information, see the description for
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              <code class="literal">auto_increment_offset</code> is also supported
              for use with <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a> tables.
</p>
</div>
<p>
            As of MySQL 8.0.18, setting the session value of this system
            variable is no longer a restricted operation.
          </p></li><li class="listitem"><p><a name="sysvar_immediate_server_version"></a>
            <a class="indexterm" name="idm46444269767072"></a>

            <a class="indexterm" name="idm46444269765968"></a>

            <a class="link" href="replication.html#sysvar_immediate_server_version"><code class="literal">immediate_server_version</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for immediate_server_version"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.14</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_immediate_server_version">immediate_server_version</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr></tbody></table>
</div>
<p>
            For internal use by replication. This session system
            variable holds the MySQL Server release number of the server
            that is the immediate master in a replication topology (for
            example, <code class="literal">80014</code> for a MySQL 8.0.14 server
            instance). If this immediate server is at a release that
            does not support the session system variable, the value of
            the variable is set to 0
            (<code class="literal">UNKNOWN_SERVER_VERSION</code>).
          </p><p>
            The value of the variable is replicated from a master to a
            slave. With this information the slave can correctly process
            data originating from a master at an older release, by
            recognizing where syntax changes or semantic changes have
            occurred between the releases involved and handling these
            appropriately. The information can also be used in a Group
            Replication environment where one or more members of the
            replication group is at a newer release than the others. The
            value of the variable can be viewed in the binary log for
            each transaction (as part of the
            <code class="literal">Gtid_log_event</code>, or
            <code class="literal">Anonymous_gtid_log_event</code> if GTIDs are not
            in use on the server), and could be helpful in debugging
            cross-version replication issues.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have either the
            <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege
            (see <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>), or
            privileges sufficient to set restricted session variables
            (see <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>). However,
            note that the variable is not intended for users to set; it
            is set automatically by the replication infrastructure.
          </p></li><li class="listitem"><p><a name="sysvar_original_server_version"></a>
            <a class="indexterm" name="idm46444269729536"></a>

            <a class="indexterm" name="idm46444269728496"></a>

            <a class="link" href="replication.html#sysvar_original_server_version"><code class="literal">original_server_version</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for original_server_version"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.14</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_original_server_version">original_server_version</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr></tbody></table>
</div>
<p>
            For internal use by replication. This session system
            variable holds the MySQL Server release number of the server
            where a transaction was originally committed (for example,
            <code class="literal">80014</code> for a MySQL 8.0.14 server
            instance). If this original server is at a release that does
            not support the session system variable, the value of the
            variable is set to 0
            (<code class="literal">UNKNOWN_SERVER_VERSION</code>). Note that when
            a release number is set by the original server, the value of
            the variable is reset to 0 if the immediate server or any
            other intervening server in the replication topology does
            not support the session system variable, and so does not
            replicate its value.
          </p><p>
            The value of the variable is set and used in the same ways
            as for the
            <a class="link" href="replication.html#sysvar_immediate_server_version"><code class="literal">immediate_server_version</code></a>
            system variable. If the value of the variable is the same as
            that for the
            <a class="link" href="replication.html#sysvar_immediate_server_version"><code class="literal">immediate_server_version</code></a>
            system variable, only the latter is recorded in the binary
            log, with an indicator that the original server version is
            the same.
          </p><p>
            In a Group Replication environment, view change log events,
            which are special transactions queued by each group member
            when a new member joins the group, are tagged with the
            server version of the group member queuing the transaction.
            This ensures that the server version of the original donor
            is known to the joining member. Because the view change log
            events queued for a particular view change have the same
            GTID on all members, for this case only, instances of the
            same GTID might have a different original server version.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have either the
            <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege
            (see <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>), or
            privileges sufficient to set restricted session variables
            (see <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>). However,
            note that the variable is not intended for users to set; it
            is set automatically by the replication infrastructure.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_enabled"></a>
            <a class="indexterm" name="idm46444269690064"></a>

            <a class="indexterm" name="idm46444269688960"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled"><code class="literal">rpl_semi_sync_master_enabled</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_enabled"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-enabled[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled">rpl_semi_sync_master_enabled</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Controls whether semisynchronous replication is enabled on
            the master. To enable or disable the plugin, set this
            variable to <code class="literal">ON</code> or <code class="literal">OFF</code>
            (or 1 or 0), respectively. The default is
            <code class="literal">OFF</code>.
          </p><p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_timeout"></a>
            <a class="indexterm" name="idm46444269654256"></a>

            <a class="indexterm" name="idm46444269653152"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_timeout"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-timeout=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout">rpl_semi_sync_master_timeout</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">10000</code></td>
</tr></tbody></table>
</div>
<p>
            A value in milliseconds that controls how long the master
            waits on a commit for acknowledgment from a slave before
            timing out and reverting to asynchronous replication. The
            default value is 10000 (10 seconds).
          </p><p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_trace_level"></a>
            <a class="indexterm" name="idm46444269620432"></a>

            <a class="indexterm" name="idm46444269619328"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_trace_level"><code class="literal">rpl_semi_sync_master_trace_level</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_trace_level"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-trace-level=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_trace_level">rpl_semi_sync_master_trace_level</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">32</code></td>
</tr></tbody></table>
</div>
<p>
            The semisynchronous replication debug trace level on the
            master. Four levels are defined:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                1 = general level (for example, time function failures)
              </p></li><li class="listitem"><p>
                16 = detail level (more verbose information)
              </p></li><li class="listitem"><p>
                32 = net wait level (more information about network
                waits)
              </p></li><li class="listitem"><p>
                64 = function level (information about function entry
                and exit)
</p></li></ul>
</div>
<p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_wait_for_slave_count"></a>
            <a class="indexterm" name="idm46444269582832"></a>

            <a class="indexterm" name="idm46444269581712"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_wait_for_slave_count"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-wait-for-slave-count=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count">rpl_semi_sync_master_wait_for_slave_count</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">65535</code></td>
</tr></tbody></table>
</div>
<p>
            The number of slave acknowledgments the master must receive
            per transaction before proceeding. By default
            <code class="literal">rpl_semi_sync_master_wait_for_slave_count</code>
            is <code class="literal">1</code>, meaning that semisynchronous
            replication proceeds after receiving a single slave
            acknowledgment. Performance is best for small values of this
            variable.
          </p><p>
            For example, if
            <code class="literal">rpl_semi_sync_master_wait_for_slave_count</code>
            is <code class="literal">2</code>, then 2 slaves must acknowledge
            receipt of the transaction before the timeout period
            configured by
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>
            for semisynchronous replication to proceed. If less slaves
            acknowledge receipt of the transaction during the timeout
            period, the master reverts to normal replication.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              This behavior also depends on
              <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_no_slave"><code class="literal">rpl_semi_sync_master_wait_no_slave</code></a>
</p>
</div>
<p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_wait_no_slave"></a>
            <a class="indexterm" name="idm46444269535584"></a>

            <a class="indexterm" name="idm46444269534544"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_no_slave"><code class="literal">rpl_semi_sync_master_wait_no_slave</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_wait_no_slave"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-wait-no-slave[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_no_slave">rpl_semi_sync_master_wait_no_slave</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            Controls whether the master waits for the timeout period
            configured by
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>
            to expire, even if the slave count drops to less than the
            number of slaves configured by
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>
            during the timeout period.
          </p><p>
            When the value of
            <code class="literal">rpl_semi_sync_master_wait_no_slave</code> is
            <code class="literal">ON</code> (the default), it is permissible for
            the slave count to drop to less than
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>
            during the timeout period. As long as enough slaves
            acknowledge the transaction before the timeout period
            expires, semisynchronous replication continues.
          </p><p>
            When the value of
            <code class="literal">rpl_semi_sync_master_wait_no_slave</code> is
            <code class="literal">OFF</code>, if the slave count drops to less
            than the number configured in
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>
            at any time during the timeout period configured by
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>,
            the master reverts to normal replication.
          </p><p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_master_wait_point"></a>
            <a class="indexterm" name="idm46444269490992"></a>

            <a class="indexterm" name="idm46444269489888"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_point"><code class="literal">rpl_semi_sync_master_wait_point</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_master_wait_point"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-master-wait-point=value</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_point">rpl_semi_sync_master_wait_point</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">AFTER_SYNC</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">AFTER_SYNC</code></p><p class="valid-value"><code class="literal">AFTER_COMMIT</code></p></td>
</tr></tbody></table>
</div>
<p>
            This variable controls the point at which a semisynchronous
            replication master waits for slave acknowledgment of
            transaction receipt before returning a status to the client
            that committed the transaction. These values are permitted:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">AFTER_SYNC</code> (the default): The master
                writes each transaction to its binary log and the slave,
                and syncs the binary log to disk. The master waits for
                slave acknowledgment of transaction receipt after the
                sync. Upon receiving acknowledgment, the master commits
                the transaction to the storage engine and returns a
                result to the client, which then can proceed.
              </p></li><li class="listitem"><p>
                <code class="literal">AFTER_COMMIT</code>: The master writes each
                transaction to its binary log and the slave, syncs the
                binary log, and commits the transaction to the storage
                engine. The master waits for slave acknowledgment of
                transaction receipt after the commit. Upon receiving
                acknowledgment, the master returns a result to the
                client, which then can proceed.
</p></li></ul>
</div>
<p>
            The replication characteristics of these settings differ as
            follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                With <code class="literal">AFTER_SYNC</code>, all clients see the
                committed transaction at the same time: After it has
                been acknowledged by the slave and committed to the
                storage engine on the master. Thus, all clients see the
                same data on the master.
              </p><p>
                In the event of master failure, all transactions
                committed on the master have been replicated to the
                slave (saved to its relay log). A crash of the master
                and failover to the slave is lossless because the slave
                is up to date. Note, however, that the master cannot be
                restarted in this scenario and must be discarded,
                because its binary log might contain uncommitted
                transactions that would cause a conflict with the slave
                when externalized after binary log recovery.
              </p></li><li class="listitem"><p>
                With <code class="literal">AFTER_COMMIT</code>, the client issuing
                the transaction gets a return status only after the
                server commits to the storage engine and receives slave
                acknowledgment. After the commit and before slave
                acknowledgment, other clients can see the committed
                transaction before the committing client.
              </p><p>
                If something goes wrong such that the slave does not
                process the transaction, then in the event of a master
                crash and failover to the slave, it is possible that
                such clients will see a loss of data relative to what
                they saw on the master.
</p></li></ul>
</div>
<p>
            This variable is available only if the master-side
            semisynchronous replication plugin is installed.
          </p><p>
            With the addition of
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_point"><code class="literal">rpl_semi_sync_master_wait_point</code></a>
            in MySQL 5.7, a version compatibility constraint was created
            because it increments the semisynchronous interface version:
            Servers for MySQL 5.7 and higher do not work with
            semisynchronous replication plugins from older versions, nor
            do servers from older versions work with semisynchronous
            replication plugins for MySQL 5.7 and higher.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-options-slave"></a>17.1.6.3 Replication Slave Options and Variables</h4>

</div>

</div>

</div>
<p>
      This section explains the server options and system variables that
      apply to slave replication servers and contains the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="replication.html#replication-optvars-slaves" title="Startup Options for Replication Slaves">Startup Options for Replication Slaves</a></p></li><li class="listitem"><p><a class="xref" href="replication.html#replication-options-slave-log-tables" title="Options for Logging Slave Status to Tables">Options for Logging Slave Status to Tables</a></p></li><li class="listitem"><p><a class="xref" href="replication.html#replication-sysvars-slaves" title="System Variables Used on Replication Slaves">System Variables Used on Replication Slaves</a></p></li></ul>
</div>
<p>
      Specify the options either on the
      <a class="link" href="programs.html#command-line-options" title="4.2.2.1 Using Options on the Command Line">command line</a> or in an
      <a class="link" href="programs.html#option-files" title="4.2.2.2 Using Option Files">option file</a>. Many of the
      options can be set while the server is running by using the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement. Specify
      system variable values using
      <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>.
    </p><p><b>Server ID. </b>
        On the master and each slave, you must set the
        <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable to
        establish a unique replication ID in the range from 1 to
        2<sup>32</sup> − 1. <span class="quote">“<span class="quote">Unique</span>”</span>
        means that each ID must be different from every other ID in use
        by any other replication master or slave. Example
        <code class="filename">my.cnf</code> file:
      </p><pre data-lang="ini" class="programlisting">[mysqld]
server-id=3</pre>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-optvars-slaves"></a>Startup Options for Replication Slaves</h5>
</div>
</div>
</div>
<p>
        This section explains startup options for controlling
        replication slave servers. Many of these options can be set
        while the server is running by using the
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement.
        Others, such as the <code class="option">--replicate-*</code> options, can
        be set only when the slave server starts. Replication-related
        system variables are discussed later in this section.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_master-info-file"></a>
            <a class="indexterm" name="idm46444269420656"></a>

            <a class="indexterm" name="idm46444269419168"></a>

            <a class="link" href="replication.html#option_mysqld_master-info-file"><code class="option">--master-info-file=<em class="replaceable"><code>file_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for master-info-file"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--master-info-file=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>8.0.18</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">master.info</code></td>
</tr></tbody></table>
</div>
<p>
            The name for the master info log, if
            <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository=FILE</code></a>
            is set. The default name is <code class="filename">master.info</code>
            in the data directory.
            <a class="link" href="replication.html#option_mysqld_master-info-file"><code class="option">--master-info-file</code></a> and the
            setting
            <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository=FILE</code></a>
            are deprecated because the use of a file for the master info
            log has been superseded by crash-safe slave tables. For
            information about the master info log, see
            <a class="xref" href="replication.html#slave-logs-status" title="17.2.4.2 Slave Status Logs">Section 17.2.4.2, “Slave Status Logs”</a>.
          </p></li><li class="listitem"><p><a name="option_mysqld_master-retry-count"></a>
            <a class="indexterm" name="idm46444269392016"></a>

            <a class="indexterm" name="idm46444269390560"></a>

            <a class="link" href="replication.html#option_mysqld_master-retry-count"><code class="option">--master-retry-count=<em class="replaceable"><code>count</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for master-retry-count"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--master-retry-count=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">86400</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The number of times that the slave tries to reconnect to the
            master before giving up. The default value is 86400 times. A
            value of 0 means <span class="quote">“<span class="quote">infinite</span>”</span>, and the slave
            attempts to connect forever. Reconnection attempts are
            triggered when the slave reaches its connection timeout
            (specified by the
            <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a> system
            variable) without receiving data or a heartbeat signal from
            the master. Reconnection is attempted at intervals set by
            the <code class="literal">MASTER_CONNECT_RETRY</code> option of the
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
            (which defaults to every 60 seconds).
          </p><p>
            This option is deprecated and will be removed in a future
            MySQL release. Use the <code class="literal">MASTER_RETRY_COUNT</code>
            option of the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
            TO</code></a> statement instead.
          </p></li><li class="listitem"><p><a name="option_mysqld_max-relay-log-size"></a>
            <a class="indexterm" name="idm46444269352352"></a>

            <a class="indexterm" name="idm46444269350896"></a>

            <a class="link" href="replication.html#option_mysqld_max-relay-log-size"><code class="option">--max-relay-log-size=<em class="replaceable"><code>size</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max_relay_log_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-relay-log-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_max_relay_log_size">max_relay_log_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr></tbody></table>
</div>
<p>
            The size at which the server rotates relay log files
            automatically. If this value is nonzero, the relay log is
            rotated automatically when its size exceeds this value. If
            this value is zero (the default), the size at which relay
            log rotation occurs is determined by the value of
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>. For more
            information, see <a class="xref" href="replication.html#slave-logs-relaylog" title="17.2.4.1 The Slave Relay Log">Section 17.2.4.1, “The Slave Relay Log”</a>.
          </p></li><li class="listitem"><p><a name="option_mysqld_relay-log-purge"></a>
            <a class="indexterm" name="idm46444269310400"></a>

            <a class="indexterm" name="idm46444269308912"></a>

            <a class="link" href="replication.html#option_mysqld_relay-log-purge"><code class="option">--relay-log-purge={0|1}</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_purge"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-purge[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_purge">relay_log_purge</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            Disable or enable automatic purging of relay logs as soon as
            they are no longer needed. The default value is 1 (enabled).
            This is a global variable that can be changed dynamically
            with <code class="literal">SET GLOBAL relay_log_purge =
            <em class="replaceable"><code>N</code></em></code>. Disabling purging of
            relay logs when enabling the
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a> option
            risks data consistency and is therefore not crash-safe.
          </p></li><li class="listitem"><p><a name="option_mysqld_relay-log-space-limit"></a>
            <a class="indexterm" name="idm46444269274848"></a>

            <a class="indexterm" name="idm46444269273392"></a>

            <a class="link" href="replication.html#option_mysqld_relay-log-space-limit"><code class="option">--relay-log-space-limit=<em class="replaceable"><code>size</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_space_limit"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-space-limit=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_space_limit">relay_log_space_limit</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            This option places an upper limit on the total size in bytes
            of all relay logs on the slave. A value of 0 means <span class="quote">“<span class="quote">no
            limit</span>”</span>. This is useful for a slave server host that
            has limited disk space. When the limit is reached, the I/O
            thread stops reading binary log events from the master
            server until the SQL thread has caught up and deleted some
            unused relay logs. Note that this limit is not absolute:
            There are cases where the SQL thread needs more events
            before it can delete relay logs. In that case, the I/O
            thread exceeds the limit until it becomes possible for the
            SQL thread to delete some relay logs because not doing so
            would cause a deadlock. You should not set
            <a class="link" href="replication.html#option_mysqld_relay-log-space-limit"><code class="option">--relay-log-space-limit</code></a> to
            less than twice the value of
            <a class="link" href="replication.html#option_mysqld_max-relay-log-size"><code class="option">--max-relay-log-size</code></a> (or
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="option">--max-binlog-size</code></a> if
            <a class="link" href="replication.html#option_mysqld_max-relay-log-size"><code class="option">--max-relay-log-size</code></a> is 0).
            In that case, there is a chance that the I/O thread waits
            for free space because
            <a class="link" href="replication.html#option_mysqld_relay-log-space-limit"><code class="option">--relay-log-space-limit</code></a> is
            exceeded, but the SQL thread has no relay log to purge and
            is unable to satisfy the I/O thread. This forces the I/O
            thread to ignore
            <a class="link" href="replication.html#option_mysqld_relay-log-space-limit"><code class="option">--relay-log-space-limit</code></a>
            temporarily.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-do-db"></a>
            <a class="indexterm" name="idm46444269224272"></a>

            <a class="indexterm" name="idm46444269222784"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=<em class="replaceable"><code>db_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-do-db"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-do-db=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter using the name of a database.
            Such filters can also be created using
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_DO_DB</code></a>.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-do-db:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            The precise effect of this replication filter depends on
            whether statement-based or row-based replication is in use.
          </p><p><b>Statement-based replication. </b>
              Tell the slave SQL thread to restrict replication to
              statements where the default database (that is, the one
              selected by <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>) is
              <em class="replaceable"><code>db_name</code></em>. To specify more than
              one database, use this option multiple times, once for
              each database; however, doing so does
              <span class="emphasis"><em>not</em></span> replicate cross-database
              statements such as <code class="literal">UPDATE
              <em class="replaceable"><code>some_db.some_table</code></em> SET
              foo='bar'</code> while a different database (or no
              database) is selected.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
              To specify multiple databases you
              <span class="emphasis"><em>must</em></span> use multiple instances of this
              option. Because database names can contain commas, if you
              supply a comma separated list then the list is treated as
              the name of a single database.
</p>
</div>
<p>
            An example of what does not work as you might expect when
            using statement-based replication: If the slave is started
            with <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=sales</code></a>
            and you issue the following statements on the master, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement is
            <span class="emphasis"><em>not</em></span> replicated:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.january SET amount=amount+1000;</pre><p>
            The main reason for this <span class="quote">“<span class="quote">check just the default
            database</span>”</span> behavior is that it is difficult from the
            statement alone to know whether it should be replicated (for
            example, if you are using multiple-table
            <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statements or
            multiple-table <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            statements that act across multiple databases). It is also
            faster to check only the default database rather than all
            databases if there is no need.
          </p><p><b>Row-based replication. </b>
              Tells the slave SQL thread to restrict replication to
              database <em class="replaceable"><code>db_name</code></em>. Only tables
              belonging to <em class="replaceable"><code>db_name</code></em> are
              changed; the current database has no effect on this.
              Suppose that the slave is started with
              <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=sales</code></a> and
              row-based replication is in effect, and then the following
              statements are run on the master:
            </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.february SET amount=amount+100;</pre><p>
            The <code class="literal">february</code> table in the
            <code class="literal">sales</code> database on the slave is changed in
            accordance with the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            statement; this occurs whether or not the
            <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement was issued.
            However, issuing the following statements on the master has
            no effect on the slave when using row-based replication and
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=sales</code></a>:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE prices.march SET amount=amount-25;</pre><p>
            Even if the statement <code class="literal">USE prices</code> were
            changed to <code class="literal">USE sales</code>, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement's
            effects would still not be replicated.
          </p><p>
            Another important difference in how
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> is handled
            in statement-based replication as opposed to row-based
            replication occurs with regard to statements that refer to
            multiple databases. Suppose that the slave is started with
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=db1</code></a>, and
            the following statements are executed on the master:
          </p><pre data-lang="sql" class="programlisting">USE db1;
UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;</pre><p>
            If you are using statement-based replication, then both
            tables are updated on the slave. However, when using
            row-based replication, only <code class="literal">table1</code> is
            affected on the slave; since <code class="literal">table2</code> is in
            a different database, <code class="literal">table2</code> on the slave
            is not changed by the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>.
            Now suppose that, instead of the <code class="literal">USE db1</code>
            statement, a <code class="literal">USE db4</code> statement had been
            used:
          </p><pre data-lang="sql" class="programlisting">USE db4;
UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;</pre><p>
            In this case, the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            statement would have no effect on the slave when using
            statement-based replication. However, if you are using
            row-based replication, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> would change
            <code class="literal">table1</code> on the slave, but not
            <code class="literal">table2</code>—in other words, only tables
            in the database named by
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> are
            changed, and the choice of default database has no effect on
            this behavior.
          </p><p>
            If you need cross-database updates to work, use
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=<em class="replaceable"><code>db_name</code></em>.%</code></a>
            instead. See <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              This option affects replication in the same manner that
              <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> affects
              binary logging, and the effects of the replication format
              on how <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>
              affects replication behavior are the same as those of the
              logging format on the behavior of
              <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a>.
            </p><p>
              This option has no effect on
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">BEGIN</code></a>,
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">COMMIT</code></a>, or
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">ROLLBACK</code></a>
              statements.
</p>
</div>
</li><li class="listitem"><p><a name="option_mysqld_replicate-ignore-db"></a>
            <a class="indexterm" name="idm46444269143072"></a>

            <a class="indexterm" name="idm46444269141616"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db=<em class="replaceable"><code>db_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-ignore-db"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-ignore-db=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter using the name of a database.
            Such filters can also be created using
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_IGNORE_DB</code></a>.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-ignore-db:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            To specify more than one database to ignore, use this option
            multiple times, once for each database. Because database
            names can contain commas, if you supply a comma separated
            list then the list will be treated as the name of a single
            database.
          </p><p>
            As with <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>,
            the precise effect of this filtering depends on whether
            statement-based or row-based replication is in use, and are
            described in the next several paragraphs.
          </p><p><b>Statement-based replication. </b>
              Tells the slave SQL thread not to replicate any statement
              where the default database (that is, the one selected by
              <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>) is
              <em class="replaceable"><code>db_name</code></em>.
            </p><p><b>Row-based replication. </b>
              Tells the slave SQL thread not to update any tables in the
              database <em class="replaceable"><code>db_name</code></em>. The default
              database has no effect.
            </p><p>
            When using statement-based replication, the following
            example does not work as you might expect. Suppose that the
            slave is started with
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db=sales</code></a>
            and you issue the following statements on the master:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.january SET amount=amount+1000;</pre><p>
            The <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement
            <span class="emphasis"><em>is</em></span> replicated in such a case because
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> applies
            only to the default database (determined by the
            <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement). Because the
            <code class="literal">sales</code> database was specified explicitly
            in the statement, the statement has not been filtered.
            However, when using row-based replication, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement's
            effects are <span class="emphasis"><em>not</em></span> propagated to the
            slave, and the slave's copy of the
            <code class="literal">sales.january</code> table is unchanged; in this
            instance,
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db=sales</code></a>
            causes <span class="emphasis"><em>all</em></span> changes made to tables in
            the master's copy of the <code class="literal">sales</code>
            database to be ignored by the slave.
          </p><p>
            You should not use this option if you are using
            cross-database updates and you do not want these updates to
            be replicated. See <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>.
          </p><p>
            If you need cross-database updates to work, use
            <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table=<em class="replaceable"><code>db_name</code></em>.%</code></a>
            instead. See <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              This option affects replication in the same manner that
              <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a> affects
              binary logging, and the effects of the replication format
              on how
              <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>
              affects replication behavior are the same as those of the
              logging format on the behavior of
              <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a>.
            </p><p>
              This option has no effect on
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">BEGIN</code></a>,
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">COMMIT</code></a>, or
              <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">ROLLBACK</code></a>
              statements.
</p>
</div>
</li><li class="listitem"><p><a name="option_mysqld_replicate-do-table"></a>
            <a class="indexterm" name="idm46444269085888"></a>

            <a class="indexterm" name="idm46444269084432"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table=<em class="replaceable"><code>db_name.tbl_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-do-table"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-do-table=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter by telling the slave SQL thread
            to restrict replication to a given table. To specify more
            than one table, use this option multiple times, once for
            each table. This works for both cross-database updates and
            default database updates, in contrast to
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>. See
            <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>. You can also create
            such a filter by issuing a
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_DO_TABLE</code></a> statement.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-do-table:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name.tbl_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            This option affects only statements that apply to tables. It
            does not affect statements that apply only to other database
            objects, such as stored routines. To filter statements
            operating on stored routines, use one or more of the
            <code class="option">--replicate-*-db</code> options.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-ignore-table"></a>
            <a class="indexterm" name="idm46444269057328"></a>

            <a class="indexterm" name="idm46444269055872"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table=<em class="replaceable"><code>db_name.tbl_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-ignore-table"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-ignore-table=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter by telling the slave SQL thread
            not to replicate any statement that updates the specified
            table, even if any other tables might be updated by the same
            statement. To specify more than one table to ignore, use
            this option multiple times, once for each table. This works
            for cross-database updates, in contrast to
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>. See
            <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>. You can also create
            such a filter by issuing a
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_IGNORE_TABLE</code></a>
            statement.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-ignore-table:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name.tbl_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            This option affects only statements that apply to tables. It
            does not affect statements that apply only to other database
            objects, such as stored routines. To filter statements
            operating on stored routines, use one or more of the
            <code class="option">--replicate-*-db</code> options.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-rewrite-db"></a>
            <a class="indexterm" name="idm46444269028640"></a>

            <a class="indexterm" name="idm46444269027184"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-rewrite-db"><code class="option">--replicate-rewrite-db=<em class="replaceable"><code>from_name</code></em>-&gt;<em class="replaceable"><code>to_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-rewrite-db"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-rewrite-db=old_name-&gt;new_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Tells the slave to create a replication filter that
            translates the default database (that is, the one selected
            by <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>) to
            <em class="replaceable"><code>to_name</code></em> if it was
            <em class="replaceable"><code>from_name</code></em> on the master. Only
            statements involving tables are affected (not statements
            such as <a class="link" href="sql-statements.html#create-database" title="13.1.12 CREATE DATABASE Statement"><code class="literal">CREATE DATABASE</code></a>,
            <a class="link" href="sql-statements.html#drop-database" title="13.1.24 DROP DATABASE Statement"><code class="literal">DROP DATABASE</code></a>, and
            <a class="link" href="sql-statements.html#alter-database" title="13.1.2 ALTER DATABASE Statement"><code class="literal">ALTER DATABASE</code></a>), and only if
            <em class="replaceable"><code>from_name</code></em> is the default database
            on the master. To specify multiple rewrites, use this option
            multiple times. The server uses the first one with a
            <em class="replaceable"><code>from_name</code></em> value that matches. The
            database name translation is done
            <span class="emphasis"><em>before</em></span> the
            <code class="option">--replicate-*</code> rules are tested. You can
            also create such a filter by issuing a
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_REWRITE_DB</code></a> statement.
          </p><p>
            If you use this option on the command line and the
            <code class="literal">&gt;</code> character is special to your command
            interpreter, quote the option value. For example:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqld --replicate-rewrite-db="<em class="replaceable"><code>olddb</code></em>-&gt;<em class="replaceable"><code>newdb</code></em>"</code></strong>
</pre><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. Specify the channel name
            followed by a colon, followed by the filter specification.
            The first colon is interpreted as a separator, and any
            subsequent colons are interpreted as literal colons. For
            example, to configure a channel specific replication filter
            on a channel named <em class="replaceable"><code>channel_1</code></em>,
            use:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqld --replicate-rewrite-db=<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name1</code></em>-&gt;<em class="replaceable"><code>db_name2</code></em></code></strong>
</pre><p>
            If you use a colon but do not specify a channel name, the
            option configures the replication filter for the default
            replication channel. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            Statements in which table names are qualified with database
            names when using this option do not work with table-level
            replication filtering options such as
            <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a>. Suppose
            we have a database named <code class="literal">a</code> on the master,
            one named <code class="literal">b</code> on the slave, each containing
            a table <code class="literal">t</code>, and have started the master
            with <code class="option">--replicate-rewrite-db='a-&gt;b'</code>. At a
            later point in time, we execute
            <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE FROM
            a.t</code></a>. In this case, no relevant filtering rule
            works, for the reasons shown here:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
                <code class="option">--replicate-do-table=a.t</code> does not work
                because the slave has table <code class="literal">t</code> in
                database <code class="literal">b</code>.
              </p></li><li class="listitem"><p>
                <code class="option">--replicate-do-table=b.t</code> does not match
                the original statement and so is ignored.
              </p></li><li class="listitem"><p>
                <code class="option">--replicate-do-table=*.t</code> is handled
                identically to
                <code class="option">--replicate-do-table=a.t</code>, and thus does
                not work, either.
</p></li></ol>
</div>
<p>
            Similarly, the <code class="option">--replication-rewrite-db</code>
            option does not work with cross-database updates.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-same-server-id"></a>
            <a class="indexterm" name="idm46444268975200"></a>

            <a class="indexterm" name="idm46444268973744"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-same-server-id"><code class="option">--replicate-same-server-id</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-same-server-id"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-same-server-id[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            This option is for use on replication slaves. The default is
            0 (<code class="literal">FALSE</code>). With this option set to 1
            (<code class="literal">TRUE</code>), the slave does not skip events
            that have its own server ID. This setting is normally useful
            only in rare configurations.
          </p><p>
            When binary logging is enabled on a replication slave, the
            combination of the
            <a class="link" href="replication.html#option_mysqld_replicate-same-server-id"><code class="option">--replicate-same-server-id</code></a>
            and <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a>
            options on the slave can cause infinite loops in replication
            if the server is part of a circular replication topology.
            (In MySQL 8.0, binary logging is enabled by default, and
            slave update logging is the default when binary logging is
            enabled.) However, the use of global transaction identifiers
            (GTIDs) prevents this situation by skipping the execution of
            transactions that have already been applied. If
            <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> is set on the
            slave, you can start the server with this combination of
            options, but you cannot change to any other GTID mode while
            the server is running. If any other GTID mode is set, the
            server does not start with this combination of options.
          </p><p>
            By default, the slave I/O thread does not write binary log
            events to the relay log if they have the slave's server ID
            (this optimization helps save disk usage). If you want to
            use
            <a class="link" href="replication.html#option_mysqld_replicate-same-server-id"><code class="option">--replicate-same-server-id</code></a>,
            be sure to start the slave with this option before you make
            the slave read its own events that you want the slave SQL
            thread to execute.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-wild-do-table"></a>
            <a class="indexterm" name="idm46444268946768"></a>

            <a class="indexterm" name="idm46444268945312"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=<em class="replaceable"><code>db_name.tbl_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-wild-do-table"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-wild-do-table=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter by telling the slave thread to
            restrict replication to statements where any of the updated
            tables match the specified database and table name patterns.
            Patterns can contain the <code class="literal">%</code> and
            <code class="literal">_</code> wildcard characters, which have the
            same meaning as for the <a class="link" href="functions.html#operator_like"><code class="literal">LIKE</code></a>
            pattern-matching operator. To specify more than one table,
            use this option multiple times, once for each table. This
            works for cross-database updates. See
            <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>. You can also create
            such a filter by issuing a
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_WILD_DO_TABLE</code></a>
            statement.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-wild-do-table:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name.tbl_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            This option applies to tables, views, and triggers. It does
            not apply to stored procedures and functions, or events. To
            filter statements operating on the latter objects, use one
            or more of the <code class="option">--replicate-*-db</code> options.
          </p><p>
            As an example,
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=foo%.bar%</code></a>
            replicates only updates that use a table where the database
            name starts with <code class="literal">foo</code> and the table name
            starts with <code class="literal">bar</code>.
          </p><p>
            If the table name pattern is <code class="literal">%</code>, it
            matches any table name and the option also applies to
            database-level statements (<a class="link" href="sql-statements.html#create-database" title="13.1.12 CREATE DATABASE Statement"><code class="literal">CREATE
            DATABASE</code></a>, <a class="link" href="sql-statements.html#drop-database" title="13.1.24 DROP DATABASE Statement"><code class="literal">DROP
            DATABASE</code></a>, and <a class="link" href="sql-statements.html#alter-database" title="13.1.2 ALTER DATABASE Statement"><code class="literal">ALTER
            DATABASE</code></a>). For example, if you use
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=foo%.%</code></a>,
            database-level statements are replicated if the database
            name matches the pattern <code class="literal">foo%</code>.
          </p><p>
            To include literal wildcard characters in the database or
            table name patterns, escape them with a backslash. For
            example, to replicate all tables of a database that is named
            <code class="literal">my_own%db</code>, but not replicate tables from
            the <code class="literal">my1ownAABCdb</code> database, you should
            escape the <code class="literal">_</code> and <code class="literal">%</code>
            characters like this:
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=my\_own\%db</code></a>.
            If you use the option on the command line, you might need to
            double the backslashes or quote the option value, depending
            on your command interpreter. For example, with the
            <span class="command"><strong>bash</strong></span> shell, you would need to type
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table=my\\_own\\%db</code></a>.
          </p></li><li class="listitem"><p><a name="option_mysqld_replicate-wild-ignore-table"></a>
            <a class="indexterm" name="idm46444268900144"></a>

            <a class="indexterm" name="idm46444268898640"></a>

            <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table=<em class="replaceable"><code>db_name.tbl_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for replicate-wild-ignore-table"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--replicate-wild-ignore-table=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            Creates a replication filter which keeps the slave thread
            from replicating a statement in which any table matches the
            given wildcard pattern. To specify more than one table to
            ignore, use this option multiple times, once for each table.
            This works for cross-database updates. See
            <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>. You can also create
            such a filter by issuing a
            <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE
            REPLICATION FILTER REPLICATE_WILD_IGNORE_TABLE</code></a>
            statement.
          </p><p>
            This option supports channel specific replication filters,
            enabling multi-source replication slaves to use specific
            filters for different sources. To configure a channel
            specific replication filter on a channel named
            <em class="replaceable"><code>channel_1</code></em> use
            <code class="option">--replicate-wild-ignore:<em class="replaceable"><code>channel_1</code></em>:<em class="replaceable"><code>db_name.tbl_name</code></em></code>.
            In this case, the first colon is interpreted as a separator
            and subsequent colons are literal colons. See
            <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>
            for more information.
          </p><p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
                Global replication filters cannot be used on a MySQL
                server instance that is configured for Group
                Replication, because filtering transactions on some
                servers would make the group unable to reach agreement
                on a consistent state. Channel specific replication
                filters can be used on replication channels that are not
                directly involved with Group Replication, such as where
                a group member also acts as a replication slave to a
                master that is outside the group. They cannot be used on
                the <code class="literal">group_replication_applier</code> or
                <code class="literal">group_replication_recovery</code> channels.
</p>
</div>
<p>
          </p><p>
            As an example,
            <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table=foo%.bar%</code></a>
            does not replicate updates that use a table where the
            database name starts with <code class="literal">foo</code> and the
            table name starts with <code class="literal">bar</code>. For
            information about how matching works, see the description of
            the <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
            option. The rules for including literal wildcard characters
            in the option value are the same as for
            <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
            as well.
          </p></li><li class="listitem"><p><a name="option_mysqld_skip-slave-start"></a>
            <a class="indexterm" name="idm46444268868368"></a>

            <a class="indexterm" name="idm46444268866880"></a>

            <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for skip-slave-start"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--skip-slave-start[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Tells the slave server not to start the slave threads when
            the server starts. To start the threads later, use a
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement.
          </p></li><li class="listitem"><p><a name="option_mysqld_slave-skip-errors"></a>
            <a class="indexterm" name="idm46444268846656"></a>

            <a class="indexterm" name="idm46444268845200"></a>

            <a class="link" href="replication.html#option_mysqld_slave-skip-errors"><code class="option">--slave-skip-errors=[<em class="replaceable"><code>err_code1</code></em>,<em class="replaceable"><code>err_code2</code></em>,...|all|ddl_exist_errors]</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave-skip-errors"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-skip-errors=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_skip_errors">slave_skip_errors</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">OFF</code></p><p class="valid-value"><code class="literal">[list of error codes]</code></p><p class="valid-value"><code class="literal">all</code></p><p class="valid-value"><code class="literal">ddl_exist_errors</code></p></td>
</tr></tbody></table>
</div>
<p>
            Normally, replication stops when an error occurs on the
            slave, which gives you the opportunity to resolve the
            inconsistency in the data manually. This option causes the
            slave SQL thread to continue replication when a statement
            returns any of the errors listed in the option value.
          </p><p>
            Do not use this option unless you fully understand why you
            are getting errors. If there are no bugs in your replication
            setup and client programs, and no bugs in MySQL itself, an
            error that stops replication should never occur.
            Indiscriminate use of this option results in slaves becoming
            hopelessly out of synchrony with the master, with you having
            no idea why this has occurred.
          </p><p>
            For error codes, you should use the numbers provided by the
            error message in your slave error log and in the output of
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>.
            <a class="xref" href="error-handling.html" title="Appendix B Errors, Error Codes, and Common Problems">Appendix B, <i>Errors, Error Codes, and Common Problems</i></a>, lists server error codes.
          </p><p>
            The shorthand value <code class="literal">ddl_exist_errors</code> is
            equivalent to the error code list
            <code class="literal">1007,1008,1050,1051,1054,1060,1061,1068,1094,1146</code>.
          </p><p>
            You can also (but should not) use the very nonrecommended
            value of <code class="literal">all</code> to cause the slave to ignore
            all error messages and keeps going regardless of what
            happens. Needless to say, if you use <code class="literal">all</code>,
            there are no guarantees regarding the integrity of your
            data. Please do not complain (or file bug reports) in this
            case if the slave's data is not anywhere close to what it is
            on the master. <span class="emphasis"><em>You have been warned</em></span>.
          </p><p>
            Examples:
          </p><pre data-lang="terminal" class="programlisting">--slave-skip-errors=1062,1053
--slave-skip-errors=all
--slave-skip-errors=ddl_exist_errors</pre></li><li class="listitem"><p><a name="option_mysqld_slave-sql-verify-checksum"></a>
            <a class="indexterm" name="idm46444268796416"></a>

            <a class="indexterm" name="idm46444268794960"></a>

            <a class="link" href="replication.html#option_mysqld_slave-sql-verify-checksum"><code class="option">--slave-sql-verify-checksum={0|1}</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave-sql-verify-checksum"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-sql-verify-checksum[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            When this option is enabled, the slave examines checksums
            read from the relay log, in the event of a mismatch, the
            slave stops with an error.
</p></li></ul>
</div>
<p>
        The following options are used internally by the MySQL test
        suite for replication testing and debugging. They are not
        intended for use in a production setting.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_abort-slave-event-count"></a>
            <a class="indexterm" name="idm46444268774848"></a>

            <a class="indexterm" name="idm46444268773392"></a>

            <a class="link" href="replication.html#option_mysqld_abort-slave-event-count"><code class="option">--abort-slave-event-count</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for abort-slave-event-count"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--abort-slave-event-count=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr></tbody></table>
</div>
<p>
            When this option is set to some positive integer
            <em class="replaceable"><code>value</code></em> other than 0 (the default)
            it affects replication behavior as follows: After the slave
            SQL thread has started, <em class="replaceable"><code>value</code></em> log
            events are permitted to be executed; after that, the slave
            SQL thread does not receive any more events, just as if the
            network connection from the master were cut. The slave
            thread continues to run, and the output from
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> displays
            <code class="literal">Yes</code> in both the
            <code class="literal">Slave_IO_Running</code> and the
            <code class="literal">Slave_SQL_Running</code> columns, but no further
            events are read from the relay log.
          </p></li><li class="listitem"><p><a name="option_mysqld_disconnect-slave-event-count"></a>
            <a class="indexterm" name="idm46444268746544"></a>

            <a class="indexterm" name="idm46444268745040"></a>

            <a class="link" href="replication.html#option_mysqld_disconnect-slave-event-count"><code class="option">--disconnect-slave-event-count</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for disconnect-slave-event-count"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--disconnect-slave-event-count=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr></tbody></table>
</div>
</li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-options-slave-log-tables"></a>Options for Logging Slave Status to Tables</h5>

</div>

</div>

</div>
<p>
        Replication slave status information is logged to an InnoDB
        table in the <code class="literal">mysql</code> database. Before MySQL
        8.0, this information could alternatively be logged to a file in
        the data directory, but the use of that format is now
        deprecated. Writing of the master info log and the relay log
        info log can be configured separately using these two system
        variables:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
</p></li></ul>
</div>
<p>
        For information about these variables, see
        <a class="xref" href="replication.html#replication-options-slave" title="17.1.6.3 Replication Slave Options and Variables">Section 17.1.6.3, “Replication Slave Options and Variables”</a>.
      </p><p>
        The slave status log tables and their contents are considered
        local to a given MySQL Server. They are not replicated, and
        changes to them are not written to the binary log.
      </p><p>
        For more information, see <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-sysvars-slaves"></a>System Variables Used on Replication Slaves</h5>

</div>

</div>

</div>
<p>
        The following list describes system variables for controlling
        replication slave servers. They can be set at server startup and
        some of them can be changed at runtime using
        <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>.
        Server options used with replication slaves are listed earlier
        in this section.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="sysvar_init_slave"></a>
            <a class="indexterm" name="idm46444268712896"></a>

            <a class="indexterm" name="idm46444268711840"></a>

            <a class="link" href="replication.html#sysvar_init_slave"><code class="literal">init_slave</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for init_slave"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--init-slave=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_init_slave">init_slave</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            This variable is similar to
            <a class="link" href="server-administration.html#sysvar_init_connect"><code class="literal">init_connect</code></a>, but is a
            string to be executed by a slave server each time the SQL
            thread starts. The format of the string is the same as for
            the <a class="link" href="server-administration.html#sysvar_init_connect"><code class="literal">init_connect</code></a> variable.
            The setting of this variable takes effect for subsequent
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statements.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              The SQL thread sends an acknowledgment to the client
              before it executes
              <a class="link" href="replication.html#sysvar_init_slave"><code class="literal">init_slave</code></a>. Therefore, it
              is not guaranteed that
              <a class="link" href="replication.html#sysvar_init_slave"><code class="literal">init_slave</code></a> has been
              executed when <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
              returns. See <a class="xref" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement">Section 13.4.2.6, “START SLAVE Statement”</a>, for more
              information.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_log_slow_slave_statements"></a>
            <a class="indexterm" name="idm46444268673712"></a>

            <a class="indexterm" name="idm46444268672224"></a>

            <a class="link" href="replication.html#sysvar_log_slow_slave_statements"><code class="literal">log_slow_slave_statements</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_slow_slave_statements"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-slow-slave-statements[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_slow_slave_statements">log_slow_slave_statements</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            When the slow query log is enabled, this variable enables
            logging for queries that have taken more than
            <a class="link" href="server-administration.html#sysvar_long_query_time"><code class="literal">long_query_time</code></a> seconds to
            execute on the slave. Note that if row-based replication is
            in use (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>),
            <a class="link" href="replication.html#sysvar_log_slow_slave_statements"><code class="literal">log_slow_slave_statements</code></a>
            has no effect. Queries are only added to the slave's slow
            query log when they are logged in statement format in the
            binary log, that is, when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a> is
            set, or when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=MIXED</code></a> is set
            and the statement is logged in statement format. Slow
            queries that are logged in row format when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=MIXED</code></a> is set,
            or that are logged when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a> is set,
            are not added to the slave's slow query log, even if
            <a class="link" href="replication.html#sysvar_log_slow_slave_statements"><code class="literal">log_slow_slave_statements</code></a>
            is enabled.
          </p><p>
            Setting
            <a class="link" href="replication.html#sysvar_log_slow_slave_statements"><code class="literal">log_slow_slave_statements</code></a>
            has no immediate effect. The state of the variable applies
            on all subsequent <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
            statements. Also note that the global setting for
            <a class="link" href="server-administration.html#sysvar_long_query_time"><code class="literal">long_query_time</code></a> applies for
            the lifetime of the SQL thread. If you change that setting,
            you must stop and restart the slave's SQL thread to
            implement the change there (for example, by issuing
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> and
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statements with
            the <code class="literal">SQL_THREAD</code> option).
          </p></li><li class="listitem"><p><a name="sysvar_master_info_repository"></a>
            <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository</code></a>
</p><a class="indexterm" name="idm46444268620576"></a><a class="indexterm" name="idm46444268619536"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for master_info_repository"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--master-info-repository={FILE|TABLE}</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_master_info_repository">master_info_repository</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">TABLE</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">FILE</code></p><p class="valid-value"><code class="literal">TABLE</code></p></td>
</tr></tbody></table>
</div>
<p>
            The setting of this variable determines whether the slave
            server logs master status and connection information to an
            <code class="literal">InnoDB</code> table in the
            <code class="literal">mysql</code> system database, or to a file in
            the data directory.
          </p><p>
            The default setting is <code class="literal">TABLE</code>. As an
            <code class="literal">InnoDB</code> table, the master info log is
            named <code class="literal">mysql.slave_master_info</code>. The
            <code class="literal">TABLE</code> setting is required when multiple
            replication channels are configured.
          </p><p>
            The <code class="literal">FILE</code> setting is deprecated, and will
            be removed in a future release. As a file, the master info
            log is named <code class="filename">master.info</code> by default.
            You can change this name using the
            <a class="link" href="replication.html#option_mysqld_master-info-file"><code class="option">--master-info-file</code></a> option.
          </p><p>
            The setting for the location of this slave status log has a
            direct influence on the effect had by the setting of the
            <a class="link" href="replication.html#sysvar_sync_master_info"><code class="literal">sync_master_info</code></a> system
            variable. You can change the setting only when no
            replication threads are executing.
          </p></li><li class="listitem"><p><a name="sysvar_max_relay_log_size"></a>
            <a class="indexterm" name="idm46444268574512"></a>

            <a class="indexterm" name="idm46444268573472"></a>

            <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max_relay_log_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-relay-log-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_max_relay_log_size">max_relay_log_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr></tbody></table>
</div>
<p>
            If a write by a replication slave to its relay log causes
            the current log file size to exceed the value of this
            variable, the slave rotates the relay logs (closes the
            current file and opens the next one). If
            <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> is 0,
            the server uses
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a> for both
            the binary log and the relay log. If
            <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> is
            greater than 0, it constrains the size of the relay log,
            which enables you to have different sizes for the two logs.
            You must set
            <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> to
            between 4096 bytes and 1GB (inclusive), or to 0. The default
            value is 0. See
            <a class="xref" href="replication.html#replication-implementation-details" title="17.2.2 Replication Implementation Details">Section 17.2.2, “Replication Implementation Details”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log"></a>
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a>
</p><a class="indexterm" name="idm46444268527888"></a><a class="indexterm" name="idm46444268526800"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log">relay_log</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr></tbody></table>
</div>
<p>
            The base name for relay log files. For the default
            replication channel, the default base name for relay logs is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin</code>.
            For non-default replication channels, the default base name
            for relay logs is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin-<em class="replaceable"><code>channel</code></em></code>,
            where <em class="replaceable"><code>channel</code></em> is the name of the
            replication channel recorded in this relay log.
          </p><p>
            The server writes the file in the data directory unless the
            base name is given with a leading absolute path name to
            specify a different directory. The server creates relay log
            files in sequence by adding a numeric suffix to the base
            name.
          </p><p>
            The relay log and relay log index on a replication server
            cannot be given the same names as the binary log and binary
            log index, whose names are specified by the
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> and
            <a class="link" href="replication.html#option_mysqld_log-bin-index"><code class="option">--log-bin-index</code></a> options. The
            server issues an error message and does not start if the
            binary log and relay log file base names would be the same.
          </p><p>
            Due to the manner in which MySQL parses server options, if
            you specify this variable at server startup, you must supply
            a value; <span class="emphasis"><em>the default base name is used only if the
            option is not actually specified</em></span>. If you specify
            the <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system
            variable at server startup without specifying a value,
            unexpected behavior is likely to result; this behavior
            depends on the other options used, the order in which they
            are specified, and whether they are specified on the command
            line or in an option file. For more information about how
            MySQL handles server options, see
            <a class="xref" href="programs.html#program-options" title="4.2.2 Specifying Program Options">Section 4.2.2, “Specifying Program Options”</a>.
          </p><p>
            If you specify this variable, the value specified is also
            used as the base name for the relay log index file. You can
            override this behavior by specifying a different relay log
            index file base name using the
            <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
            variable.
          </p><p>
            When the server reads an entry from the index file, it
            checks whether the entry contains a relative path. If it
            does, the relative part of the path is replaced with the
            absolute path set using the
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable.
            An absolute path remains unchanged; in such a case, the
            index must be edited manually to enable the new path or
            paths to be used.
          </p><p>
            You may find the <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a>
            system variable useful in performing the following tasks:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                Creating relay logs whose names are independent of host
                names.
              </p></li><li class="listitem"><p>
                If you need to put the relay logs in some area other
                than the data directory because your relay logs tend to
                be very large and you do not want to decrease
                <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a>.
              </p></li><li class="listitem"><p>
                To increase speed by using load-balancing between disks.
</p></li></ul>
</div>
<p>
            You can obtain the relay log file name (and path) from the
            <a class="link" href="replication.html#sysvar_relay_log_basename"><code class="literal">relay_log_basename</code></a> system
            variable.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_basename"></a>
            <a class="indexterm" name="idm46444268477584"></a>

            <a class="indexterm" name="idm46444268476544"></a>

            <a class="link" href="replication.html#sysvar_relay_log_basename"><code class="literal">relay_log_basename</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_basename"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_basename">relay_log_basename</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">datadir + '/' + hostname + '-relay-bin'</code></td>
</tr></tbody></table>
</div>
<p>
            Holds the name and complete path to the relay log file. This
            variable is set by the server and is read only.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_index"></a>
            <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a>
</p><a class="indexterm" name="idm46444268446336"></a><a class="indexterm" name="idm46444268445248"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_index"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-index=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_index">relay_log_index</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">*host_name*-relay-bin.index</code></td>
</tr></tbody></table>
</div>
<p>
            The name for the relay log index file. If you do not specify
            this variable, but the
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable
            is specified, its value is used as the default base name for
            the relay log index file. If
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> is also not
            specified, then for the default replication channel, the
            default name is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin.index</code>,
            using the name of the host machine. For non-default
            replication channels, the default name is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin-<em class="replaceable"><code>channel</code></em>.index</code>,
            where <em class="replaceable"><code>channel</code></em> is the name of the
            replication channel recorded in this relay log index.
          </p><p>
            The default location for relay log files is the data
            directory, or any other location that was specified using
            the <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system
            variable. You can use the
            <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
            variable to specify an alternative location, by adding a
            leading absolute path name to the base name to specify a
            different directory.
          </p><p>
            The relay log and relay log index on a replication server
            cannot be given the same names as the binary log and binary
            log index, whose names are specified by the
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> and
            <a class="link" href="replication.html#option_mysqld_log-bin-index"><code class="option">--log-bin-index</code></a> options. The
            server issues an error message and does not start if the
            binary log and relay log file base names would be the same.
          </p><p>
            Due to the manner in which MySQL parses server options, if
            you specify this variable at server startup, you must supply
            a value; <span class="emphasis"><em>the default base name is used only if the
            option is not actually specified</em></span>. If you specify
            the <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
            variable at server startup without specifying a value,
            unexpected behavior is likely to result; this behavior
            depends on the other options used, the order in which they
            are specified, and whether they are specified on the command
            line or in an option file. For more information about how
            MySQL handles server options, see
            <a class="xref" href="programs.html#program-options" title="4.2.2 Specifying Program Options">Section 4.2.2, “Specifying Program Options”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_info_file"></a>
            <a class="link" href="replication.html#sysvar_relay_log_info_file"><code class="literal">relay_log_info_file</code></a>
</p><a class="indexterm" name="idm46444268398080"></a><a class="indexterm" name="idm46444268397040"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_info_file"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-info-file=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>8.0.18</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_info_file">relay_log_info_file</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">relay-log.info</code></td>
</tr></tbody></table>
</div>
<p>
            The name of the file in which the slave records information
            about the relay logs, when
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=FILE</code></a>.
            If
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=TABLE</code></a>,
            it is the file name that would be used in case the
            repository was changed to <code class="literal">FILE</code>). The
            default name is <code class="filename">relay-log.info</code> in the
            data directory.
            <a class="link" href="replication.html#sysvar_relay_log_info_file"><code class="literal">relay_log_info_file</code></a> and the
            setting
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=FILE</code></a>
            are deprecated, as the use of a file for the relay log info
            log has been superseded by crash-safe slave tables. For
            information about the relay log info log, see
            <a class="xref" href="replication.html#slave-logs-status" title="17.2.4.2 Slave Status Logs">Section 17.2.4.2, “Slave Status Logs”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_info_repository"></a>
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
</p><a class="indexterm" name="idm46444268354768"></a><a class="indexterm" name="idm46444268353664"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_info_repository"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-info-repository=value</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_info_repository">relay_log_info_repository</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">TABLE</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">FILE</code></p><p class="valid-value"><code class="literal">TABLE</code></p></td>
</tr></tbody></table>
</div>
<p>
            The setting of this variable determines whether the slave
            server logs its position in the relay logs to an
            <code class="literal">InnoDB</code> table in the
            <code class="literal">mysql</code> system database, or to a file in
            the data directory.
          </p><p>
            The default setting is <code class="literal">TABLE</code>. As an
            <code class="literal">InnoDB</code> table, the relay log info log is
            named <code class="literal">mysql.slave_relay_log_info</code>. The
            <code class="literal">TABLE</code> setting is required when multiple
            replication channels are configured. The
            <code class="literal">TABLE</code> setting for the relay log info log
            is also required to make replication resilient to unexpected
            halts, for which the
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a> option
            must also be enabled. See
            <a class="xref" href="replication.html#replication-implementation-crash-safe" title="Making replication resilient to unexpected halts">Making replication resilient to unexpected halts</a> for
            more information.
          </p><p>
            The <code class="literal">FILE</code> setting is deprecated, and will
            be removed in a future release. As a file, the relay log
            info log is named <code class="filename">relay-log.info</code> by
            default, and you can change this name using the
            <a class="link" href="replication.html#sysvar_relay_log_info_file"><code class="literal">relay_log_info_file</code></a> system
            variable.
          </p><p>
            The setting for the location of this slave status log has a
            direct influence on the effect had by the setting of the
            <a class="link" href="replication.html#sysvar_sync_relay_log_info"><code class="literal">sync_relay_log_info</code></a> system
            variable. You can change the setting only when no
            replication threads are executing.
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_purge"></a>
            <a class="indexterm" name="idm46444268305440"></a>

            <a class="indexterm" name="idm46444268304432"></a>

            <a class="link" href="replication.html#sysvar_relay_log_purge"><code class="literal">relay_log_purge</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_purge"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-purge[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_purge">relay_log_purge</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            Disables or enables automatic purging of relay log files as
            soon as they are not needed any more. The default value is 1
            (<code class="literal">ON</code>).
          </p></li><li class="listitem"><p><a name="sysvar_relay_log_recovery"></a>
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a>
</p><a class="indexterm" name="idm46444268270480"></a><a class="indexterm" name="idm46444268268992"></a><a class="indexterm" name="idm46444268267952"></a><a class="indexterm" name="idm46444268266880"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_recovery"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-recovery[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_recovery">relay_log_recovery</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            If enabled, this variable enables automatic relay log
            recovery immediately following server startup. The recovery
            process creates a new relay log file, initializes the SQL
            thread position to this new relay log, and initializes the
            I/O thread to the SQL thread position. Reading of the relay
            log from the master then continues. This global variable is
            read-only at runtime. Its value can set with the
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a> option
            at slave startup, which should be used following an
            unexpected halt of a replication slave to ensure that no
            possibly corrupted relay logs are processed, and must be
            used in order to guarantee a crash-safe slave. The default
            value is 0 (disabled).
          </p><p>
            To provide a crash-safe slave, this variable must be enabled
            (set to 1),
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
            must be set to <code class="literal">TABLE</code>, and
            <a class="link" href="replication.html#sysvar_relay_log_purge"><code class="literal">relay_log_purge</code></a> must be
            enabled. Enabling
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a> when
            <a class="link" href="replication.html#sysvar_relay_log_purge"><code class="literal">relay_log_purge</code></a> is disabled
            risks reading the relay log from files that were not purged,
            leading to data inconsistency, and is therefore not
            crash-safe. See
            <a class="xref" href="replication.html#replication-implementation-crash-safe" title="Making replication resilient to unexpected halts">Making replication resilient to unexpected halts</a>, for
            more information.
          </p><p>
            When using a multithreaded slave (in other words
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> is
            greater than 0), inconsistencies such as gaps can occur in
            the sequence of transactions that have been executed from
            the relay log. Enabling
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a> when
            there are inconsistencies causes an error and the option has
            no effect. The solution in this situation is to issue
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE
            UNTIL SQL_AFTER_MTS_GAPS</code></a>, which brings the server
            to a more consistent state, then issue
            <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> to remove the
            relay logs. See
            <a class="xref" href="replication.html#replication-features-transaction-inconsistencies" title="17.5.1.33 Replication and Transaction Inconsistencies">Section 17.5.1.33, “Replication and Transaction Inconsistencies”</a>
            for more information.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              This variable does not affect the following Group
              Replication channels:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <code class="literal">group_replication_applier</code>
                </p></li><li class="listitem"><p>
                  <code class="literal">group_replication_recovery</code>
</p></li></ul>
</div>
<p>
              Any other channels running on a group are affected, such
              as a channel which is replicating from an outside master
              or another group.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_relay_log_space_limit"></a>
            <a class="indexterm" name="idm46444268215856"></a>

            <a class="indexterm" name="idm46444268214816"></a>

            <a class="link" href="replication.html#sysvar_relay_log_space_limit"><code class="literal">relay_log_space_limit</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for relay_log_space_limit"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--relay-log-space-limit=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_relay_log_space_limit">relay_log_space_limit</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The maximum amount of space to use for all relay logs.
          </p></li><li class="listitem"><p><a name="sysvar_report_host"></a>
            <a class="indexterm" name="idm46444268173360"></a>

            <a class="indexterm" name="idm46444268172304"></a>

            <a class="link" href="replication.html#sysvar_report_host"><code class="literal">report_host</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for report_host"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--report-host=host_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_report_host">report_host</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            The host name or IP address of the slave to be reported to
            the master during slave registration. This value appears in
            the output of <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE
            HOSTS</code></a> on the master server. Leave the value unset
            if you do not want the slave to register itself with the
            master.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              It is not sufficient for the master to simply read the IP
              address of the slave from the TCP/IP socket after the
              slave connects. Due to NAT and other routing issues, that
              IP may not be valid for connecting to the slave from the
              master or other hosts.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_report_password"></a>
            <a class="indexterm" name="idm46444268140944"></a>

            <a class="indexterm" name="idm46444268139888"></a>

            <a class="link" href="replication.html#sysvar_report_password"><code class="literal">report_password</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for report_password"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--report-password=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_report_password">report_password</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            The account password of the slave to be reported to the
            master during slave registration. This value appears in the
            output of <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE HOSTS</code></a> on
            the master server if the master was started with
            <a class="link" href="replication.html#option_mysqld_show-slave-auth-info"><code class="option">--show-slave-auth-info</code></a>.
          </p><p>
            Although the name of this variable might imply otherwise,
            <a class="link" href="replication.html#sysvar_report_password"><code class="literal">report_password</code></a> is not
            connected to the MySQL user privilege system and so is not
            necessarily (or even likely to be) the same as the password
            for the MySQL replication user account.
          </p></li><li class="listitem"><p><a name="sysvar_report_port"></a>
            <a class="indexterm" name="idm46444268106848"></a>

            <a class="indexterm" name="idm46444268105792"></a>

            <a class="link" href="replication.html#sysvar_report_port"><code class="literal">report_port</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for report_port"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--report-port=port_num</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_report_port">report_port</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">[slave_port]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">65535</code></td>
</tr></tbody></table>
</div>
<p>
            The TCP/IP port number for connecting to the slave, to be
            reported to the master during slave registration. Set this
            only if the slave is listening on a nondefault port or if
            you have a special tunnel from the master or other clients
            to the slave. If you are not sure, do not use this option.
          </p><p>
            The default value for this option is the port number
            actually used by the slave. This is also the default value
            displayed by <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE
            HOSTS</code></a>.
          </p></li><li class="listitem"><p><a name="sysvar_report_user"></a>
            <a class="indexterm" name="idm46444268065696"></a>

            <a class="indexterm" name="idm46444268064640"></a>

            <a class="link" href="replication.html#sysvar_report_user"><code class="literal">report_user</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for report_user"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--report-user=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_report_user">report_user</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            The account user name of the slave to be reported to the
            master during slave registration. This value appears in the
            output of <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE HOSTS</code></a> on
            the master server if the master was started with
            <a class="link" href="replication.html#option_mysqld_show-slave-auth-info"><code class="option">--show-slave-auth-info</code></a>.
          </p><p>
            Although the name of this variable might imply otherwise,
            <a class="link" href="replication.html#sysvar_report_user"><code class="literal">report_user</code></a> is not
            connected to the MySQL user privilege system and so is not
            necessarily (or even likely to be) the same as the name of
            the MySQL replication user account.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_read_size"></a>
            <a class="indexterm" name="idm46444268031600"></a>

            <a class="indexterm" name="idm46444268030144"></a>

            <a class="link" href="replication.html#sysvar_rpl_read_size"><code class="literal">rpl_read_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_read_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-read-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_read_size">rpl_read_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">8192</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">8192</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The <a class="link" href="replication.html#sysvar_rpl_read_size"><code class="literal">rpl_read_size</code></a> system
            variable controls the minimum amount of data in bytes that
            is read from the binary log files and relay log files. If
            heavy disk I/O activity for these files is impeding
            performance for the database, increasing the read size might
            reduce file reads and I/O stalls when the file data is not
            currently cached by the operating system.
          </p><p>
            The minimum and default value for
            <a class="link" href="replication.html#sysvar_rpl_read_size"><code class="literal">rpl_read_size</code></a> is 8192
            bytes. The value must be a multiple of 4KB. Note that a
            buffer the size of this value is allocated for each thread
            that reads from the binary log and relay log files,
            including dump threads on masters and coordinator threads on
            slaves. Setting a large value might therefore have an impact
            on memory consumption for servers.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_slave_enabled"></a>
            <a class="indexterm" name="idm46444267988800"></a>

            <a class="indexterm" name="idm46444267987696"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_enabled"><code class="literal">rpl_semi_sync_slave_enabled</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_slave_enabled"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-slave-enabled[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_enabled">rpl_semi_sync_slave_enabled</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Controls whether semisynchronous replication is enabled on
            the slave. To enable or disable the plugin, set this
            variable to <code class="literal">ON</code> or <code class="literal">OFF</code>
            (or 1 or 0), respectively. The default is
            <code class="literal">OFF</code>.
          </p><p>
            This variable is available only if the slave-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_semi_sync_slave_trace_level"></a>
            <a class="indexterm" name="idm46444267953056"></a>

            <a class="indexterm" name="idm46444267951952"></a>

            <a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_trace_level"><code class="literal">rpl_semi_sync_slave_trace_level</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_semi_sync_slave_trace_level"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-semi-sync-slave-trace-level=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_trace_level">rpl_semi_sync_slave_trace_level</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">32</code></td>
</tr></tbody></table>
</div>
<p>
            The semisynchronous replication debug trace level on the
            slave. See
            <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_trace_level"><code class="literal">rpl_semi_sync_master_trace_level</code></a>
            for the permissible values.
          </p><p>
            This variable is available only if the slave-side
            semisynchronous replication plugin is installed.
          </p></li><li class="listitem"><p><a name="sysvar_rpl_stop_slave_timeout"></a>
            <a class="indexterm" name="idm46444267918112"></a>

            <a class="indexterm" name="idm46444267916624"></a>

            <a class="link" href="replication.html#sysvar_rpl_stop_slave_timeout"><code class="literal">rpl_stop_slave_timeout</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for rpl_stop_slave_timeout"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--rpl-stop-slave-timeout=seconds</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_rpl_stop_slave_timeout">rpl_stop_slave_timeout</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">31536000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">2</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">31536000</code></td>
</tr></tbody></table>
</div>
<p>
            You can control the length of time (in seconds) that
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> waits before
            timing out by setting this variable. This can be used to
            avoid deadlocks between <code class="literal">STOP SLAVE</code> and
            other slave SQL statements using different client
            connections to the slave.
          </p><p>
            The maximum and default value of
            <code class="literal">rpl_stop_slave_timeout</code> is 31536000
            seconds (1 year). The minimum is 2 seconds. Changes to this
            variable take effect for subsequent
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> statements.
          </p><p>
            This variable affects only the client that issues a
            <code class="literal">STOP SLAVE</code> statement. When the timeout is
            reached, the issuing client returns an error message stating
            that the command execution is incomplete. The client then
            stops waiting for the slave threads to stop, but the slave
            threads continue to try to stop, and the <code class="literal">STOP
            SLAVE</code> instruction remains in effect. Once the
            slave threads are no longer busy, the <code class="literal">STOP
            SLAVE</code> statement is executed and the slave stops.
          </p></li><li class="listitem"><p><a name="sysvar_slave_checkpoint_group"></a>
            <a class="link" href="replication.html#sysvar_slave_checkpoint_group"><code class="literal">slave_checkpoint_group</code></a>
</p><a class="indexterm" name="idm46444267869920"></a><a class="indexterm" name="idm46444267868432"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_checkpoint_group"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-checkpoint-group=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_checkpoint_group">slave_checkpoint_group</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">512</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">32</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">524280</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Block Size</strong></span></td>
<td><code class="literal">8</code></td>
</tr></tbody></table>
</div>
<p>
            Sets the maximum number of transactions that can be
            processed by a multithreaded slave before a checkpoint
            operation is called to update its status as shown by
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>. Setting
            this variable has no effect on slaves for which
            multithreading is not enabled. Setting this variable has no
            immediate effect. The state of the variable applies on all
            subsequent <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
            commands.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Multithreaded slaves are not currently supported by NDB
              Cluster, which silently ignores the setting for this
              variable. See
              <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-issues" title="22.6.3 Known Issues in NDB Cluster Replication">Section 22.6.3, “Known Issues in NDB Cluster Replication”</a>, for
              more information.
</p>
</div>
<p>
            This variable works in combination with the
            <a class="link" href="replication.html#sysvar_slave_checkpoint_period"><code class="literal">slave_checkpoint_period</code></a>
            system variable in such a way that, when either limit is
            exceeded, the checkpoint is executed and the counters
            tracking both the number of transactions and the time
            elapsed since the last checkpoint are reset.
          </p><p>
            The minimum allowed value for this variable is 32, unless
            the server was built using
            <a class="link" href="installing.html#option_cmake_with_debug"><code class="option">-DWITH_DEBUG</code></a>, in which case
            the minimum value is 1. The effective value is always a
            multiple of 8; you can set it to a value that is not such a
            multiple, but the server rounds it down to the next lower
            multiple of 8 before storing the value.
            (<span class="emphasis"><em>Exception</em></span>: No such rounding is
            performed by the debug server.) Regardless of how the server
            was built, the default value is 512, and the maximum allowed
            value is 524280.
          </p></li><li class="listitem"><p><a name="sysvar_slave_checkpoint_period"></a>
            <a class="link" href="replication.html#sysvar_slave_checkpoint_period"><code class="literal">slave_checkpoint_period</code></a>
</p><a class="indexterm" name="idm46444267818688"></a><a class="indexterm" name="idm46444267817200"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_checkpoint_period"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-checkpoint-period=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_checkpoint_period">slave_checkpoint_period</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">300</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4G</code></td>
</tr></tbody></table>
</div>
<p>
            Sets the maximum time (in milliseconds) that is allowed to
            pass before a checkpoint operation is called to update the
            status of a multithreaded slave as shown by
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>. Setting
            this variable has no effect on slaves for which
            multithreading is not enabled. Setting this variable takes
            effect for all replication channels immediately, including
            running channels.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Multithreaded slaves are not currently supported by NDB
              Cluster, which silently ignores the setting for this
              variable. See
              <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-issues" title="22.6.3 Known Issues in NDB Cluster Replication">Section 22.6.3, “Known Issues in NDB Cluster Replication”</a>, for
              more information.
</p>
</div>
<p>
            This variable works in combination with the
            <a class="link" href="replication.html#sysvar_slave_checkpoint_group"><code class="literal">slave_checkpoint_group</code></a>
            system variable in such a way that, when either limit is
            exceeded, the checkpoint is executed and the counters
            tracking both the number of transactions and the time
            elapsed since the last checkpoint are reset.
          </p><p>
            The minimum allowed value for this variable is 1, unless the
            server was built using
            <a class="link" href="installing.html#option_cmake_with_debug"><code class="option">-DWITH_DEBUG</code></a>, in which case
            the minimum value is 0. Regardless of how the server was
            built, the default value is 300, and the maximum possible
            value is 4294967296 (4GB).
          </p></li><li class="listitem"><p><a name="sysvar_slave_compressed_protocol"></a>
            <a class="link" href="replication.html#sysvar_slave_compressed_protocol"><code class="literal">slave_compressed_protocol</code></a>
</p><a class="indexterm" name="idm46444267772608"></a><a class="indexterm" name="idm46444267771504"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_compressed_protocol"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-compressed-protocol[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>8.0.18</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_compressed_protocol">slave_compressed_protocol</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Whether to use compression of the master/slave protocol if
            both master and slave support it. If this variable is
            disabled (the default), connections are uncompressed.
            Changes to this variable take effect on subsequent
            connection attempts; this includes after issuing a
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement, as
            well as reconnections made by a running I/O thread (for
            example, after setting the
            <code class="literal">MASTER_RETRY_COUNT</code> option for the
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement).
          </p><p>
            Binary log transaction compression (available as of MySQL
            8.0.20), which is activated by the
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>
            system variable, can also be used to save bandwidth. If you
            use binary log transaction compression in combination with
            protocol compression, protocol compression has less
            opportunity to act on the data, but can still compress
            headers and those events and transaction payloads that are
            uncompressed. For more information on binary log transaction
            compression, see
            <a class="xref" href="server-administration.html#binary-log-transaction-compression" title="5.4.4.5 Binary Log Transaction Compression">Section 5.4.4.5, “Binary Log Transaction Compression”</a>.
          </p><p>
            As of MySQL 8.0.18, if
            <a class="link" href="replication.html#sysvar_slave_compressed_protocol"><code class="literal">slave_compressed_protocol</code></a>
            is enabled, it takes precedence over any
            <code class="literal">MASTER_COMPRESSION_ALGORITHMS</code> option
            specified for the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
            TO</code></a> statement. In this case, connections to the
            master use <code class="literal">zlib</code> compression if both the
            master and slave support that algorithm. If
            <a class="link" href="replication.html#sysvar_slave_compressed_protocol"><code class="literal">slave_compressed_protocol</code></a>
            is disabled, the value of
            <code class="literal">MASTER_COMPRESSION_ALGORITHMS</code> applies.
            For more information, see
            <a class="xref" href="programs.html#connection-compression-control" title="4.2.6 Connection Compression Control">Section 4.2.6, “Connection Compression Control”</a>.
          </p><p>
            As of MySQL 8.0.18, this system variable is deprecated. It
            will be removed in a future MySQL version. See
            <a class="xref" href="programs.html#connection-compression-legacy-configuration" title="Legacy Connection Compression Configuration">Legacy Connection Compression Configuration</a>.
          </p></li><li class="listitem"><p><a name="sysvar_slave_exec_mode"></a>
            <a class="indexterm" name="idm46444267722992"></a>

            <a class="indexterm" name="idm46444267721936"></a>

            <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_exec_mode"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-exec-mode=mode</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_exec_mode">slave_exec_mode</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><p class="valid-value"><code class="literal">IDEMPOTENT</code> (NDB)</p><p class="valid-value"><code class="literal">STRICT</code> (Other)</p></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">IDEMPOTENT</code></p><p class="valid-value"><code class="literal">STRICT</code></p></td>
</tr></tbody></table>
</div>
<p>
            Controls how a slave thread resolves conflicts and errors
            during replication. <code class="literal">IDEMPOTENT</code> mode
            causes suppression of duplicate-key and no-key-found errors;
            <code class="literal">STRICT</code> means no such suppression takes
            place.
          </p><p>
            <code class="literal">IDEMPOTENT</code> mode is intended for use in
            multi-master replication, circular replication, and some
            other special replication scenarios for NDB Cluster
            Replication. (See
            <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-multi-master" title="22.6.10 NDB Cluster Replication: Multi-Master and Circular Replication">Section 22.6.10, “NDB Cluster Replication: Multi-Master and Circular Replication”</a>,
            and
            <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-conflict-resolution" title="22.6.11 NDB Cluster Replication Conflict Resolution">Section 22.6.11, “NDB Cluster Replication Conflict Resolution”</a>,
            for more information.) NDB Cluster ignores any value
            explicitly set for
            <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a>, and always
            treats it as <code class="literal">IDEMPOTENT</code>.
          </p><p>
            In MySQL Server 8.0, <code class="literal">STRICT</code>
            mode is the default value.
          </p><p>
            Setting this variable takes immediate effect for all
            replication channels, including running channels.
          </p><p>
            For storage engines other than
            <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a>,
            <span class="emphasis"><em><code class="literal">IDEMPOTENT</code> mode should be used
            only when you are absolutely sure that duplicate-key errors
            and key-not-found errors can safely be ignored</em></span>.
            It is meant to be used in fail-over scenarios for NDB
            Cluster where multi-master replication or circular
            replication is employed, and is not recommended for use in
            other cases.
          </p></li><li class="listitem"><p><a name="sysvar_slave_load_tmpdir"></a>
            <a class="link" href="replication.html#sysvar_slave_load_tmpdir"><code class="literal">slave_load_tmpdir</code></a>
</p><a class="indexterm" name="idm46444267671040"></a><a class="indexterm" name="idm46444267670000"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_load_tmpdir"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-load-tmpdir=dir_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_load_tmpdir">slave_load_tmpdir</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Directory name</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">Value of --tmpdir</code></td>
</tr></tbody></table>
</div>
<p>
            The name of the directory where the slave creates temporary
            files. Setting this variable takes effect for all
            replication channels immediately, including running
            channels. The variable value is by default equal to the
            value of the <a class="link" href="server-administration.html#sysvar_tmpdir"><code class="literal">tmpdir</code></a> system
            variable, or the default that applies when that system
            variable is not specified.
          </p><p>
            When the slave SQL thread replicates a
            <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> statement, it
            extracts the file to be loaded from the relay log into
            temporary files, and then loads these into the table. If the
            file loaded on the master is huge, the temporary files on
            the slave are huge, too. Therefore, it might be advisable to
            use this option to tell the slave to put temporary files in
            a directory located in some file system that has a lot of
            available space. In that case, the relay logs are huge as
            well, so you might also want to set the
            <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable
            to place the relay logs in that file system.
          </p><p>
            The directory specified by this option should be located in
            a disk-based file system (not a memory-based file system) so
            that the temporary files used to replicate
            <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> statements can
            survive machine restarts. The directory also should not be
            one that is cleared by the operating system during the
            system startup process. However, replication can now
            continue after a restart if the temporary files have been
            removed.
          </p></li><li class="listitem"><p><a name="sysvar_slave_max_allowed_packet"></a>
            <a class="link" href="replication.html#sysvar_slave_max_allowed_packet"><code class="literal">slave_max_allowed_packet</code></a>
</p><a class="indexterm" name="idm46444267630800"></a><a class="indexterm" name="idm46444267629696"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_max_allowed_packet"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-max-allowed-packet=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_max_allowed_packet">slave_max_allowed_packet</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1024</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr></tbody></table>
</div>
<p>
            This option sets the maximum packet size in bytes that the
            slave SQL and I/O threads can handle. Setting this variable
            takes effect for all replication channels immediately,
            including running channels. It is possible for a replication
            master to write binary log events longer than its
            <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> setting
            once the event header is added. The setting for
            <a class="link" href="replication.html#sysvar_slave_max_allowed_packet"><code class="literal">slave_max_allowed_packet</code></a>
            must be larger than the
            <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> setting
            on the master, so that large updates using row-based
            replication do not cause replication to fail.
          </p><p>
            This global variable always has a value that is a positive
            integer multiple of 1024; if you set it to some value that
            is not, the value is rounded down to the next highest
            multiple of 1024 for it is stored or used; setting
            <code class="literal">slave_max_allowed_packet</code> to 0 causes 1024
            to be used. (A truncation warning is issued in all such
            cases.) The default and maximum value is 1073741824 (1 GB);
            the minimum is 1024.
          </p></li><li class="listitem"><p><a name="sysvar_slave_net_timeout"></a>
            <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a>
</p><a class="indexterm" name="idm46444267585584"></a><a class="indexterm" name="idm46444267584544"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_net_timeout"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-net-timeout=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_net_timeout">slave_net_timeout</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">60</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr></tbody></table>
</div>
<p>
            The number of seconds to wait for more data or a heartbeat
            signal from the master before the slave considers the
            connection broken, aborts the read, and tries to reconnect.
            Setting this variable has no immediate effect. The state of
            the variable applies on all subsequent
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> commands.
          </p><p>
            The default value is 60 seconds (one minute). The first
            retry occurs immediately after the timeout. The interval
            between retries is controlled by the
            <code class="literal">MASTER_CONNECT_RETRY</code> option for the
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement,
            and the number of reconnection attempts is limited by the
            <code class="literal">MASTER_RETRY_COUNT</code> option for the
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement.
          </p><p>
            The heartbeat interval, which stops the connection timeout
            occurring in the absence of data if the connection is still
            good, is controlled by the
            <code class="literal">MASTER_HEARTBEAT_PERIOD</code> option for the
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement.
            The heartbeat interval defaults to half the value of
            <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a>, and it
            is recorded in the master info log and shown in the
            <a class="link" href="performance-schema.html#replication-connection-configuration-table" title="26.12.11.1 The replication_connection_configuration Table"><code class="literal">replication_connection_configuration</code></a>
            Performance Schema table. Note that a change to the value or
            default setting of
            <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a> does not
            automatically change the heartbeat interval, whether that
            has been set explicitly or is using a previously calculated
            default. If the connection timeout is changed, you must also
            issue <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> to
            adjust the heartbeat interval to an appropriate value so
            that it occurs before the connection timeout.
          </p></li><li class="listitem"><p><a name="sysvar_slave_parallel_type"></a>
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a>
</p><a class="indexterm" name="idm46444267535216"></a><a class="indexterm" name="idm46444267534176"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_parallel_type"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-parallel-type=value</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_parallel_type">slave_parallel_type</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">DATABASE</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">DATABASE</code></p><p class="valid-value"><code class="literal">LOGICAL_CLOCK</code></p></td>
</tr></tbody></table>
</div>
<p>
            For multithreaded slaves (replication slaves on which
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> is
            set to a value greater than 0),
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a>
            specifies the policy used to decide which transactions are
            allowed to execute in parallel on the slave. The variable
            has no effect on slaves for which multithreading is not
            enabled. The possible values are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">LOGICAL_CLOCK</code>: Transactions that are
                part of the same binary log group commit on a master are
                applied in parallel on a slave. The dependencies between
                transactions are tracked based on their timestamps to
                provide additional parallelization where possible. When
                this value is set, the
                <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
                system variable can be used on the master to specify
                that write sets are used for parallelization in place of
                timestamps, if a write set is available for the
                transaction and gives improved results compared to
                timestamps.
              </p></li><li class="listitem"><p>
                <code class="literal">DATABASE</code>: Transactions that update
                different databases are applied in parallel. This value
                is only appropriate if data is partitioned into multiple
                databases which are being updated independently and
                concurrently on the master. There must be no
                cross-database constraints, as such constraints may be
                violated on the slave.
</p></li></ul>
</div>
<p>
            When
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            is set, you can only use <code class="literal">LOGICAL_CLOCK</code>.
          </p><p>
            When your replication topology uses multiple levels of
            slaves, <code class="literal">LOGICAL_CLOCK</code> may achieve less
            parallelization for each level the slave is away from the
            master. You can reduce this effect by using
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            on the master to specify that write sets are used instead of
            timestamps for parallelization where possible.
          </p><p>
            When binary log transaction compression is enabled using the
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>
            system variable, if
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a> is set
            to <code class="literal">DATABASE</code>, all the databases affected
            by the transaction are mapped before the transaction is
            scheduled. The use of binary log transaction compression
            with the <code class="literal">DATABASE</code> policy can reduce
            parallelism compared to uncompressed transactions, which are
            mapped and scheduled for each event.
          </p></li><li class="listitem"><p><a name="sysvar_slave_parallel_workers"></a>
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a>
</p><a class="indexterm" name="idm46444267479120"></a><a class="indexterm" name="idm46444267478080"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_parallel_workers"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-parallel-workers=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_parallel_workers">slave_parallel_workers</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1024</code></td>
</tr></tbody></table>
</div>
<p>
            Enables multithreading on the slave and sets the number of
            slave applier threads for executing replication transactions
            in parallel. When the value is a number greater than 0, the
            slave is a multithreaded slave with the specified number of
            applier threads, plus a coordinator thread to manage them.
            If you are using multiple replication channels, each channel
            has this number of threads.


</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Multithreaded slaves are not currently supported by NDB
              Cluster, which silently ignores the setting for this
              variable. See
              <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-issues" title="22.6.3 Known Issues in NDB Cluster Replication">Section 22.6.3, “Known Issues in NDB Cluster Replication”</a>, for
              more information.
</p>
</div>
<p>
            Retrying of transactions is supported when multithreading is
            enabled on a slave. When
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>,



            transactions on a slave are externalized on the slave in the
            same order as they appear in the slave's relay log. The way
            in which transactions are distributed among applier threads
            is configured by
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a>.
          </p><p>
            To disable parallel execution, set this option to 0, which
            gives the slave a single applier thread and no coordinator
            thread. With this setting, the
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a> and
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order</code></a>
            system variables have no effect and are ignored.
          </p><p>
            Setting
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> has
            no immediate effect. The state of the variable applies on
            all subsequent <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
            statements.
          </p></li><li class="listitem"><p><a name="sysvar_slave_pending_jobs_size_max"></a>
            <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a>
</p><a class="indexterm" name="idm46444267428384"></a><a class="indexterm" name="idm46444267426880"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_pending_jobs_size_max"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-pending-jobs-size-max=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max">slave_pending_jobs_size_max</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span> (≥ 8.0.12)</td>
<td><code class="literal">128M</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span> (8.0.11)</td>
<td><code class="literal">16M</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1024</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">16EiB</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Block Size</strong></span></td>
<td><code class="literal">1024</code></td>
</tr></tbody></table>
</div>
<p>
            For multithreaded slaves, this variable sets the maximum
            amount of memory (in bytes) available to slave worker queues
            holding events not yet applied. Setting this variable has no
            effect on slaves for which multithreading is not enabled.
            Setting this variable has no immediate effect. The state of
            the variable applies on all subsequent
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> commands.
          </p><p>
            The minimum possible value for this variable is 1024 bytes;
            the default is 128MB. The maximum possible value is
            18446744073709551615 (16 exbibytes). Values that are not
            exact multiples of 1024 bytes are rounded down to the next
            lower multiple of 1024 bytes prior to being stored.
          </p><p>
            The value of this variable is a soft limit and can be set to
            match the normal workload. If an unusually large event
            exceeds this size, the transaction is held until all the
            slave workers have empty queues, and then processed. All
            subsequent transactions are held until the large transaction
            has been completed.
          </p></li><li class="listitem"><p><a name="sysvar_slave_preserve_commit_order"></a>
            <a class="indexterm" name="idm46444267380832"></a>

            <a class="indexterm" name="idm46444267379376"></a>

            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_preserve_commit_order"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-preserve-commit-order[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_preserve_commit_order">slave_preserve_commit_order</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            For multithreaded slaves (replication slaves on which
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> is
            set to a value greater than 0), setting
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            ensures that transactions are executed and committed on the
            slave in the same order as they appear in the slave's
            relay log. This prevents gaps in the sequence of
            transactions that have been executed from the slave's relay
            log, and preserves the same transaction history on the slave
            as on the master (with the limitations listed below). This
            variable has no effect on slaves for which multithreading is
            not enabled.
          </p><p>
            Up to and including MySQL 8.0.18, setting
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            requires that binary logging
            (<a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a>) and slave update
            logging (<a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a>)
            are enabled on the slave, which are the default settings
            from MySQL 8.0. From MySQL 8.0.19, binary logging and slave
            update logging are not required on the slave to set
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>,
            and can be disabled if wanted. In all releases, setting
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            requires that
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a> is set
            to <code class="literal">LOGICAL_CLOCK</code>, which is
            <span class="emphasis"><em>not</em></span> the default setting. Before
            changing the value of
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order</code></a>
            and <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a>,
            the slave SQL thread (for all replication channels if you
            are using multiple replication channels) must be stopped.
          </p><p>
            When
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=0</code></a>
            is set, which is the default, the transactions that a
            multithreaded slave applies in parallel may commit out of
            order. Therefore, checking for the most recently executed
            transaction does not guarantee that all previous
            transactions from the master have been executed on the
            slave. There is a chance of gaps in the sequence of
            transactions that have been executed from the slave's relay
            log. This has implications for logging and recovery when
            using a multithreaded slave. See
            <a class="xref" href="replication.html#replication-features-transaction-inconsistencies" title="17.5.1.33 Replication and Transaction Inconsistencies">Section 17.5.1.33, “Replication and Transaction Inconsistencies”</a>
            for more information.
          </p><p>
            When
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            is set, the executing worker thread waits until all previous
            transactions are committed before committing. While a given
            thread is waiting for other worker threads to commit their
            transactions, it reports its status as <code class="literal">Waiting for
            preceding transaction to commit</code>. With this mode, a
            multithreaded slave never enters a state that the master was
            not in. This supports the use of replication for read
            scale-out. See
            <a class="xref" href="replication.html#replication-solutions-scaleout" title="17.4.5 Using Replication for Scale-Out">Section 17.4.5, “Using Replication for Scale-Out”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>

<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
                  does not prevent master log position lag, where
                  <code class="literal">Exec_master_log_pos</code> is behind the
                  position up to which transactions have been executed.
                  See
                  <a class="xref" href="replication.html#replication-features-transaction-inconsistencies" title="17.5.1.33 Replication and Transaction Inconsistencies">Section 17.5.1.33, “Replication and Transaction Inconsistencies”</a>.
                </p></li><li class="listitem"><p>
                  <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
                  does not preserve the commit order and transaction
                  history if the slave uses filters on its binary log,
                  such as <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a>.
                </p></li><li class="listitem"><p>
                  <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
                  does not preserve the order of non-transactional DML
                  updates. These might commit before transactions that
                  precede them in the relay log, which might result in
                  gaps in the sequence of transactions that have been
                  executed from the slave's relay log.
                </p></li><li class="listitem"><p>
                  In releases before MySQL 8.0.19,
                  <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
                  does not preserve the order of statements with an
                  <code class="literal">IF EXISTS</code> clause when the object
                  concerned does not exist. These might commit before
                  transactions that precede them in the relay log, which
                  might result in gaps in the sequence of transactions
                  that have been executed from the slave's relay log.
                </p></li><li class="listitem"><p>
                  A limitation to preserving the commit order on the
                  slave can occur if statement-based replication is in
                  use, and both transactional and non-transactional
                  storage engines participate in a non-XA transaction
                  that is rolled back on the master. Normally, non-XA
                  transactions that are rolled back on the master are
                  not replicated to the slave, but in this particular
                  situation, the transaction might be replicated to the
                  slave. If this does happen, a multithreaded slave
                  without binary logging does not handle the transaction
                  rollback, so the commit order on the slave diverges
                  from the relay log order of the transactions in that
                  case.
</p></li></ul>
</div>

</div>
</li><li class="listitem"><p><a name="sysvar_slave_rows_search_algorithms"></a>
            <a class="link" href="replication.html#sysvar_slave_rows_search_algorithms"><code class="literal">slave_rows_search_algorithms</code></a>
</p><a class="indexterm" name="idm46444267310192"></a><a class="indexterm" name="idm46444267309088"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_rows_search_algorithms"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-rows-search-algorithms=value</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>8.0.18</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_rows_search_algorithms">slave_rows_search_algorithms</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Set</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">INDEX_SCAN,HASH_SCAN</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">TABLE_SCAN,INDEX_SCAN</code></p><p class="valid-value"><code class="literal">INDEX_SCAN,HASH_SCAN</code></p><p class="valid-value"><code class="literal">TABLE_SCAN,HASH_SCAN</code></p><p class="valid-value"><code class="literal">TABLE_SCAN,INDEX_SCAN,HASH_SCAN</code> (equivalent to INDEX_SCAN,HASH_SCAN)</p></td>
</tr></tbody></table>
</div>
<p>
            When preparing batches of rows for row-based logging and
            replication, this system variable controls how the rows are
            searched for matches, in particular whether hash scans are
            used. The use of this system variable is now deprecated. The
            default setting <code class="literal">INDEX_SCAN,HASH_SCAN</code> is
            optimal for performance and works correctly in all
            scenarios.
          </p></li><li class="listitem"><p><a name="sysvar_slave_skip_errors"></a>
            <a class="indexterm" name="idm46444267268160"></a>

            <a class="indexterm" name="idm46444267267120"></a>

            <a class="link" href="replication.html#sysvar_slave_skip_errors"><code class="literal">slave_skip_errors</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave-skip-errors"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-skip-errors=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_skip_errors">slave_skip_errors</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">OFF</code></p><p class="valid-value"><code class="literal">[list of error codes]</code></p><p class="valid-value"><code class="literal">all</code></p><p class="valid-value"><code class="literal">ddl_exist_errors</code></p></td>
</tr></tbody></table>
</div>
<p>
            Normally, replication stops when an error occurs on the
            slave, which gives you the opportunity to resolve the
            inconsistency in the data manually. This variable causes the
            slave SQL thread to continue replication when a statement
            returns any of the errors listed in the variable value.
          </p></li><li class="listitem"><p><a name="sysvar_slave_sql_verify_checksum"></a>
            <a class="indexterm" name="idm46444267228592"></a>

            <a class="indexterm" name="idm46444267227488"></a>

            <a class="link" href="replication.html#sysvar_slave_sql_verify_checksum"><code class="literal">slave_sql_verify_checksum</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_sql_verify_checksum"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-sql-verify-checksum[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_sql_verify_checksum">slave_sql_verify_checksum</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            Cause the slave SQL thread to verify data using the
            checksums read from the relay log. In the event of a
            mismatch, the slave stops with an error. Setting this
            variable takes effect for all replication channels
            immediately, including running channels.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              The slave I/O thread always reads checksums if possible
              when accepting events from over the network.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_slave_transaction_retries"></a>
            <a class="indexterm" name="idm46444267194352"></a>

            <a class="indexterm" name="idm46444267193248"></a>

            <a class="link" href="replication.html#sysvar_slave_transaction_retries"><code class="literal">slave_transaction_retries</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_transaction_retries"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-transaction-retries=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_transaction_retries">slave_transaction_retries</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">10</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            Sets the maximum number of times for replication slave SQL
            threads on a single-threaded or multithreaded slave to
            automatically retry failed transactions before stopping.
            Setting this variable takes effect for all replication
            channels immediately, including running channels. The
            default value is 10. Setting the variable to 0 disables
            automatic retrying of transactions.
          </p><p>
            If a replication slave SQL thread fails to execute a
            transaction because of an
            <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> deadlock or because the
            transaction's execution time exceeded
            <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>'s
            <a class="link" href="innodb-storage-engine.html#sysvar_innodb_lock_wait_timeout"><code class="literal">innodb_lock_wait_timeout</code></a> or
            <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a>'s
            <a class="link" href="mysql-cluster.html#ndbparam-ndbd-transactiondeadlockdetectiontimeout"><code class="literal">TransactionDeadlockDetectionTimeout</code></a>
            or
            <a class="link" href="mysql-cluster.html#ndbparam-ndbd-transactioninactivetimeout"><code class="literal">TransactionInactiveTimeout</code></a>,
            it automatically retries
            <a class="link" href="replication.html#sysvar_slave_transaction_retries"><code class="literal">slave_transaction_retries</code></a>
            times before stopping with an error. Transactions with a
            non-temporary error are not retried.
          </p><p>
            The Performance Schema table
            <a class="link" href="performance-schema.html#replication-applier-status-table" title="26.12.11.4 The replication_applier_status Table"><code class="literal">replication_applier_status</code></a>
            shows the number of retries that took place on each
            replication channel, in the
            <code class="literal">COUNT_TRANSACTIONS_RETRIES</code> column. The
            Performance Schema table
            <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>
            shows detailed information on transaction retries by
            individual applier threads on a single-threaded or
            multithreaded replication slave, and identifies the errors
            that caused the last transaction and the transaction
            currently in progress to be reattempted.
          </p></li><li class="listitem"><p><a name="sysvar_slave_type_conversions"></a>
            <a class="indexterm" name="idm46444267137056"></a>

            <a class="indexterm" name="idm46444267136016"></a>

            <a class="link" href="replication.html#sysvar_slave_type_conversions"><code class="literal">slave_type_conversions</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for slave_type_conversions"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--slave-type-conversions=set</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_slave_type_conversions">slave_type_conversions</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Set</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal"></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">ALL_LOSSY</code></p><p class="valid-value"><code class="literal">ALL_NON_LOSSY</code></p><p class="valid-value"><code class="literal">ALL_SIGNED</code></p><p class="valid-value"><code class="literal">ALL_UNSIGNED</code></p></td>
</tr></tbody></table>
</div>
<p>
            Controls the type conversion mode in effect on the slave
            when using row-based replication. Its value is a
            comma-delimited set of zero or more elements from the list:
            <code class="literal">ALL_LOSSY</code>,
            <code class="literal">ALL_NON_LOSSY</code>,
            <code class="literal">ALL_SIGNED</code>,
            <code class="literal">ALL_UNSIGNED</code>. Set this variable to an
            empty string to disallow type conversions between the master
            and the slave. Setting this variable takes effect for all
            replication channels immediately, including running
            channels.
          </p><p>
            For additional information on type conversion modes
            applicable to attribute promotion and demotion in row-based
            replication, see
            <a class="xref" href="replication.html#replication-features-attribute-promotion" title="Row-based replication: attribute promotion and demotion">Row-based replication: attribute promotion and demotion</a>.
          </p></li><li class="listitem"><p><a name="sysvar_sql_slave_skip_counter"></a>
            <a class="indexterm" name="idm46444267093168"></a>

            <a class="indexterm" name="idm46444267092128"></a>

            <a class="link" href="replication.html#sysvar_sql_slave_skip_counter"><code class="literal">sql_slave_skip_counter</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sql_slave_skip_counter"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sql_slave_skip_counter">sql_slave_skip_counter</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr></tbody></table>
</div>
<p>
            The number of events from the master that a slave server
            should skip. Setting the option has no immediate effect. The
            variable applies to the next <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
            SLAVE</code></a> statement; the next
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement also
            changes the value back to 0. When this variable is set to a
            nonzero value and there are multiple replication channels
            configured, the <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
            statement can only be used with the <code class="literal">FOR CHANNEL
            <em class="replaceable"><code>channel</code></em></code> clause.
          </p><p>
            This option is incompatible with GTID-based replication, and
            must not be set to a nonzero value when
            <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>. If you need
            to skip transactions when employing GTIDs, use
            <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> from the
            master instead. See
            <a class="xref" href="replication.html#replication-gtids-failover-empty" title="Injecting empty transactions">Injecting empty transactions</a>, for
            information about how to do this.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
              If skipping the number of events specified by setting this
              variable would cause the slave to begin in the middle of
              an event group, the slave continues to skip until it finds
              the beginning of the next event group and begins from that
              point. For more information, see
              <a class="xref" href="sql-statements.html#set-global-sql-slave-skip-counter" title="13.4.2.5 SET GLOBAL sql_slave_skip_counter Statement">Section 13.4.2.5, “SET GLOBAL sql_slave_skip_counter Statement”</a>.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_sync_master_info"></a>
            <a class="indexterm" name="idm46444267055584"></a>

            <a class="indexterm" name="idm46444267054576"></a>

            <a class="link" href="replication.html#sysvar_sync_master_info"><code class="literal">sync_master_info</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sync_master_info"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--sync-master-info=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sync_master_info">sync_master_info</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">10000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The effects of this variable on a replication slave depend
            on whether the slave's
            <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository</code></a> is
            set to <code class="literal">FILE</code> or <code class="literal">TABLE</code>,
            as explained in the following paragraphs.
          </p><p><b>master_info_repository = FILE. </b>
              If the value of <code class="literal">sync_master_info</code> is
              greater than 0, the slave synchronizes its
              <code class="filename">master.info</code> file to disk (using
              <code class="literal">fdatasync()</code>) after every
              <code class="literal">sync_master_info</code> events. If it is 0,
              the MySQL server performs no synchronization of the
              <code class="filename">master.info</code> file to disk; instead,
              the server relies on the operating system to flush its
              contents periodically as with any other file.
            </p><p><b>master_info_repository = TABLE. </b>
              If the value of <code class="literal">sync_master_info</code> is
              greater than 0, the slave updates its master info
              repository table after every
              <code class="literal">sync_master_info</code> events. If it is 0,
              the table is never updated.
            </p><p>
            The default value for <code class="literal">sync_master_info</code> is
            10000. Setting this variable takes effect for all
            replication channels immediately, including running
            channels.
          </p></li><li class="listitem"><p><a name="sysvar_sync_relay_log"></a>
            <a class="indexterm" name="idm46444267001056"></a>

            <a class="indexterm" name="idm46444267000000"></a>

            <a class="link" href="replication.html#sysvar_sync_relay_log"><code class="literal">sync_relay_log</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sync_relay_log"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--sync-relay-log=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sync_relay_log">sync_relay_log</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">10000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            If the value of this variable is greater than 0, the MySQL
            server synchronizes its relay log to disk (using
            <code class="literal">fdatasync()</code>) after every
            <code class="literal">sync_relay_log</code> events are written to the
            relay log. Setting this variable takes effect for all
            replication channels immediately, including running
            channels.
          </p><p>
            Setting <code class="literal">sync_relay_log</code> to 0 causes no
            synchronization to be done to disk; in this case, the server
            relies on the operating system to flush the relay log's
            contents from time to time as for any other file.
          </p><p>
            A value of 1 is the safest choice because in the event of a
            crash you lose at most one event from the relay log.
            However, it is also the slowest choice (unless the disk has
            a battery-backed cache, which makes synchronization very
            fast).
          </p></li><li class="listitem"><p><a name="sysvar_sync_relay_log_info"></a>
            <a class="indexterm" name="idm46444266954864"></a>

            <a class="indexterm" name="idm46444266953824"></a>

            <a class="link" href="replication.html#sysvar_sync_relay_log_info"><code class="literal">sync_relay_log_info</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sync_relay_log_info"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--sync-relay-log-info=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sync_relay_log_info">sync_relay_log_info</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">10000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The default value for <code class="literal">sync_relay_log_info</code>
            is 10000. Setting this variable takes effect for all
            replication channels immediately, including running
            channels.
          </p><p>
            The effects of this variable on the replication slave depend
            on the server's
            <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
            setting (<code class="literal">FILE</code> or
            <code class="literal">TABLE</code>). If the setting is
            <code class="literal">TABLE</code>, the effects of the variable also
            depend on whether the storage engine used by the relay log
            info table is transactional (such as
            <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>) or not transactional
            (<a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a>). The effects of these
            factors on the behavior of the server for
            <code class="literal">sync_relay_log_info</code> values of zero and
            greater than zero are as follows:
</p>
<div class="variablelist">
<dl class="variablelist"><dt><span class="term">
                <code class="literal">sync_relay_log_info = 0</code>
</span></dt><dd>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">FILE</code>, the MySQL
                      server performs no synchronization of the
                      <code class="filename">relay-log.info</code> file to disk;
                      instead, the server relies on the operating system
                      to flush its contents periodically as with any
                      other file.
                    </p></li><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">TABLE</code>, and the
                      storage engine for that table is transactional,
                      the table is updated after each transaction. (The
                      <code class="literal">sync_relay_log_info</code> setting is
                      effectively ignored in this case.)
                    </p></li><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">TABLE</code>, and the
                      storage engine for that table is not
                      transactional, the table is never updated.
</p></li></ul>
</div>
</dd><dt><span class="term">
                <code class="literal">sync_relay_log_info =
                <em class="replaceable"><code>N</code></em> &gt; 0</code>
</span></dt><dd>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">FILE</code>, the slave
                      synchronizes its
                      <code class="filename">relay-log.info</code> file to disk
                      (using <code class="literal">fdatasync()</code>) after every
                      <em class="replaceable"><code>N</code></em> transactions.
                    </p></li><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">TABLE</code>, and the
                      storage engine for that table is transactional,
                      the table is updated after each transaction. (The
                      <code class="literal">sync_relay_log_info</code> setting is
                      effectively ignored in this case.)
                    </p></li><li class="listitem"><p>
                      If
                      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
                      is set to <code class="literal">TABLE</code>, and the
                      storage engine for that table is not
                      transactional, the table is updated after every
                      <em class="replaceable"><code>N</code></em> events.
</p></li></ul>
</div>
</dd></dl>
</div>
</li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-options-binary-log"></a>17.1.6.4 Binary Logging Options and Variables</h4>

</div>

</div>

</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="replication.html#replication-optvars-binlog" title="Startup Options Used with Binary Logging">Startup Options Used with Binary Logging</a></p></li><li class="listitem"><p><a class="xref" href="replication.html#replication-sysvars-binlog" title="System Variables Used with Binary Logging">System Variables Used with Binary Logging</a></p></li></ul>
</div>
<p>
      You can use the <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> options and system
      variables that are described in this section to affect the
      operation of the binary log as well as to control which statements
      are written to the binary log. For additional information about
      the binary log, see <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>. For additional
      information about using MySQL server options and system variables,
      see <a class="xref" href="server-administration.html#server-options" title="5.1.7 Server Command Options">Section 5.1.7, “Server Command Options”</a>, and
      <a class="xref" href="server-administration.html#server-system-variables" title="5.1.8 Server System Variables">Section 5.1.8, “Server System Variables”</a>.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h5 class="title"><a name="replication-optvars-binlog"></a>Startup Options Used with Binary Logging</h5>
</div>
</div>
</div>
<p>
        The following list describes startup options for enabling and
        configuring the binary log. System variables used with binary
        logging are discussed later in this section.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_binlog-row-event-max-size"></a>
            <a class="indexterm" name="idm46444266866048"></a>

            <a class="indexterm" name="idm46444266864592"></a>

            <a class="link" href="replication.html#option_mysqld_binlog-row-event-max-size"><code class="option">--binlog-row-event-max-size=<em class="replaceable"><code>N</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog-row-event-max-size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-row-event-max-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span> (≥ 8.0.14)</td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_event_max_size">binlog_row_event_max_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span> (≥ 8.0.14)</td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span> (≥ 8.0.14)</td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span> (≥ 8.0.14)</td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">8192</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">256</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            When row-based binary logging is used, this setting is a
            soft limit on the maximum size of a row-based binary log
            event, in bytes. Where possible, rows stored in the binary
            log are grouped into events with a size not exceeding the
            value of this setting. If an event cannot be split, the
            maximum size can be exceeded. The value must be (or else
            gets rounded down to) a multiple of 256. The default is 8192
            bytes.
          </p></li><li class="listitem"><p><a name="option_mysqld_log-bin"></a>
            <a class="indexterm" name="idm46444266821984"></a>

            <a class="indexterm" name="idm46444266820528"></a>

            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin[=<em class="replaceable"><code>base_name</code></em>]</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log-bin"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-bin=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr></tbody></table>
</div>
<p>
            Specifies the base name to use for binary log files. With
            binary logging enabled, the server logs all statements that
            change data to the binary log, which is used for backup and
            replication. The binary log is a sequence of files with a
            base name and numeric extension. The
            <code class="option">--log-bin</code> option value is the base name for
            the log sequence. The server creates binary log files in
            sequence by adding a numeric suffix to the base name.
          </p><p>
            If you do not supply the <code class="option">--log-bin</code> option,
            MySQL uses <code class="filename">binlog</code> as the default base
            name for the binary log files. For compatibility with
            earlier releases, if you supply the
            <code class="option">--log-bin</code> option with no string or with an
            empty string, the base name defaults to
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-bin</code>,
            using the name of the host machine.
          </p><p>
            The default location for binary log files is the data
            directory. You can use the <code class="option">--log-bin</code> option
            to specify an alternative location, by adding a leading
            absolute path name to the base name to specify a different
            directory. When the server reads an entry from the binary
            log index file, which tracks the binary log files that have
            been used, it checks whether the entry contains a relative
            path. If it does, the relative part of the path is replaced
            with the absolute path set using the
            <code class="option">--log-bin</code> option. An absolute path recorded
            in the binary log index file remains unchanged; in such a
            case, the index file must be edited manually to enable a new
            path or paths to be used. The binary log file base name and
            any specified path are available as the
            <a class="link" href="replication.html#sysvar_log_bin_basename"><code class="literal">log_bin_basename</code></a> system
            variable.
          </p><p>
            In earlier MySQL versions, binary logging was disabled by
            default, and was enabled if you specified the
            <code class="option">--log-bin</code> option. From MySQL 8.0, binary
            logging is enabled by default, whether or not you specify
            the <code class="option">--log-bin</code> option. The exception is if
            you use <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> to initialize the data
            directory manually by invoking it with the
            <code class="option">--initialize</code> or
            <code class="option">--initialize-insecure</code> option, when binary
            logging is disabled by default. It is possible to enable
            binary logging in this case by specifying the
            <code class="option">--log-bin</code> option. When binary logging is
            enabled, the <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> system
            variable, which shows the status of binary logging on the
            server, is set to ON.


          </p><p>
            To disable binary logging, you can specify the
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            or
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--disable-log-bin</code></a>
            option at startup. If either of these options is specified
            and <code class="option">--log-bin</code> is also specified, the option
            specified later takes precedence. When binary logging is
            disabled, the <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a>
            system variable is set to OFF.
          </p><p>
            When GTIDs are in use on the server, if you disable binary
            logging when restarting the server after an abnormal
            shutdown, some GTIDs are likely to be lost, causing
            replication to fail. In a normal shutdown, the set of GTIDs
            from the current binary log file is saved in the
            <code class="literal">mysql.gtid_executed</code> table. Following an
            abnormal shutdown where this did not happen, during recovery
            the GTIDs are added to the table from the binary log file,
            provided that binary logging is still enabled. If binary
            logging is disabled for the server restart, the server
            cannot access the binary log file to recover the GTIDs, so
            replication cannot be started. Binary logging can be
            disabled safely after a normal shutdown.
          </p><p>
            The <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a> and
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="option">--slave-preserve-commit-order</code></a>
            options require binary logging. If you disable binary
            logging, either omit these options, or specify
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> and
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="option">--skip-slave-preserve-commit-order</code></a>.
            MySQL disables these options by default when
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            or
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--disable-log-bin</code></a>
            is specified. If you specify
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a> or
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="option">--slave-preserve-commit-order</code></a>
            together with
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            or
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--disable-log-bin</code></a>,
            a warning or error message is issued.
          </p><p>
            In MySQL 5.7, a server ID had to be specified when binary
            logging was enabled, or the server would not start. In MySQL
            8.0, the
            <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable
            is set to 1 by default. The server can now be started with
            this default server ID when binary logging is enabled, but
            an informational message is issued if you do not specify a
            server ID explicitly by setting the
            <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable.
            For servers that are used in a replication topology, you
            must specify a unique nonzero server ID for each server.
          </p><p>
            For information on the format and management of the binary
            log, see <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
          </p></li><li class="listitem"><p><a name="option_mysqld_log-bin-index"></a>
            <a class="indexterm" name="idm46444266769376"></a>

            <a class="indexterm" name="idm46444266767888"></a>

            <a class="link" href="replication.html#option_mysqld_log-bin-index"><code class="option">--log-bin-index[=<em class="replaceable"><code>file_name</code></em>]</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log-bin-index"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-bin-index=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin_index">log_bin_index</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr></tbody></table>
</div>
<p>
            The name for the binary log index file, which contains the
            names of the binary log files. By default, it has the same
            location and base name as the value specified for the binary
            log files using the <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a>
            option, plus the extension <code class="filename">.index</code>. If
            you do not specify <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a>,
            the default binary log index file name is
            <code class="filename">binlog.index</code>. If you specify
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> option with no
            string or an empty string, the default binary log index file
            name is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-bin.index</code>,
            using the name of the host machine.
          </p><p>
            For information on the format and management of the binary
            log, see <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
</p></li></ul>
</div>
<p><b>Statement selection options. </b>
          The options in the following list affect which statements are
          written to the binary log, and thus sent by a replication
          master server to its slaves. There are also options for slave
          servers that control which statements received from the master
          should be executed or ignored. For details, see
          <a class="xref" href="replication.html#replication-options-slave" title="17.1.6.3 Replication Slave Options and Variables">Section 17.1.6.3, “Replication Slave Options and Variables”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_binlog-do-db"></a>
            <a class="indexterm" name="idm46444266729152"></a>

            <a class="indexterm" name="idm46444266727664"></a>

            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=<em class="replaceable"><code>db_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog-do-db"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-do-db=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            This option affects binary logging in a manner similar to
            the way that
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> affects
            replication.
          </p><p>
            The effects of this option depend on whether the
            statement-based or row-based logging format is in use, in
            the same way that the effects of
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> depend on
            whether statement-based or row-based replication is in use.
            You should keep in mind that the format used to log a given
            statement may not necessarily be the same as that indicated
            by the value of
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>. For example,
            DDL statements such as <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
            TABLE</code></a> and <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
            TABLE</code></a> are always logged as statements, without
            regard to the logging format in effect, so the following
            statement-based rules for <code class="option">--binlog-do-db</code>
            always apply in determining whether or not the statement is
            logged.
          </p><p><b>Statement-based logging. </b>
              Only those statements are written to the binary log where
              the default database (that is, the one selected by
              <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>) is
              <em class="replaceable"><code>db_name</code></em>. To specify more than
              one database, use this option multiple times, once for
              each database; however, doing so does
              <span class="emphasis"><em>not</em></span> cause cross-database statements
              such as <code class="literal">UPDATE
              <em class="replaceable"><code>some_db.some_table</code></em> SET
              foo='bar'</code> to be logged while a different
              database (or no database) is selected.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
              To specify multiple databases you
              <span class="emphasis"><em>must</em></span> use multiple instances of this
              option. Because database names can contain commas, the
              list will be treated as the name of a single database if
              you supply a comma-separated list.
</p>
</div>
<p>
            An example of what does not work as you might expect when
            using statement-based logging: If the server is started with
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=sales</code></a> and you
            issue the following statements, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement is
            <span class="emphasis"><em>not</em></span> logged:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.january SET amount=amount+1000;</pre><p>
            The main reason for this <span class="quote">“<span class="quote">just check the default
            database</span>”</span> behavior is that it is difficult from the
            statement alone to know whether it should be replicated (for
            example, if you are using multiple-table
            <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statements or
            multiple-table <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            statements that act across multiple databases). It is also
            faster to check only the default database rather than all
            databases if there is no need.
          </p><p>
            Another case which may not be self-evident occurs when a
            given database is replicated even though it was not
            specified when setting the option. If the server is started
            with <code class="option">--binlog-do-db=sales</code>, the following
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement is logged
            even though <code class="literal">prices</code> was not included when
            setting <code class="option">--binlog-do-db</code>:
          </p><pre data-lang="sql" class="programlisting">        
USE sales;
UPDATE prices.discounts SET percentage = percentage + 10;</pre><p>
            Because <code class="literal">sales</code> is the default database
            when the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement is
            issued, the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> is logged.
          </p><p><b>Row-based logging. </b>
              Logging is restricted to database
              <em class="replaceable"><code>db_name</code></em>. Only changes to tables
              belonging to <em class="replaceable"><code>db_name</code></em> are
              logged; the default database has no effect on this.
              Suppose that the server is started with
              <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=sales</code></a> and
              row-based logging is in effect, and then the following
              statements are executed:
            </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.february SET amount=amount+100;</pre><p>
            The changes to the <code class="literal">february</code> table in the
            <code class="literal">sales</code> database are logged in accordance
            with the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement;
            this occurs whether or not the
            <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement was issued.
            However, when using the row-based logging format and
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=sales</code></a>, changes
            made by the following <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            are not logged:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE prices.march SET amount=amount-25;</pre><p>
            Even if the <code class="literal">USE prices</code> statement were
            changed to <code class="literal">USE sales</code>, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement's
            effects would still not be written to the binary log.
          </p><p>
            Another important difference in
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> handling for
            statement-based logging as opposed to the row-based logging
            occurs with regard to statements that refer to multiple
            databases. Suppose that the server is started with
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=db1</code></a>, and the
            following statements are executed:
          </p><pre data-lang="sql" class="programlisting">USE db1;
UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;</pre><p>
            If you are using statement-based logging, the updates to
            both tables are written to the binary log. However, when
            using the row-based format, only the changes to
            <code class="literal">table1</code> are logged;
            <code class="literal">table2</code> is in a different database, so it
            is not changed by the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>.
            Now suppose that, instead of the <code class="literal">USE db1</code>
            statement, a <code class="literal">USE db4</code> statement had been
            used:
          </p><pre data-lang="sql" class="programlisting">USE db4;
UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;</pre><p>
            In this case, the <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>
            statement is not written to the binary log when using
            statement-based logging. However, when using row-based
            logging, the change to <code class="literal">table1</code> is logged,
            but not that to <code class="literal">table2</code>—in other
            words, only changes to tables in the database named by
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> are logged,
            and the choice of default database has no effect on this
            behavior.
          </p></li><li class="listitem"><p><a name="option_mysqld_binlog-ignore-db"></a>
            <a class="indexterm" name="idm46444266652416"></a>

            <a class="indexterm" name="idm46444266650928"></a>

            <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db=<em class="replaceable"><code>db_name</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog-ignore-db"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-ignore-db=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
            This option affects binary logging in a manner similar to
            the way that
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> affects
            replication.
          </p><p>
            The effects of this option depend on whether the
            statement-based or row-based logging format is in use, in
            the same way that the effects of
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> depend
            on whether statement-based or row-based replication is in
            use. You should keep in mind that the format used to log a
            given statement may not necessarily be the same as that
            indicated by the value of
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>. For example,
            DDL statements such as <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
            TABLE</code></a> and <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
            TABLE</code></a> are always logged as statements, without
            regard to the logging format in effect, so the following
            statement-based rules for
            <code class="option">--binlog-ignore-db</code> always apply in
            determining whether or not the statement is logged.
          </p><p><b>Statement-based logging. </b>
              Tells the server to not log any statement where the
              default database (that is, the one selected by
              <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>) is
              <em class="replaceable"><code>db_name</code></em>.
            </p><p>
            When there is no default database, no
            <code class="option">--binlog-ignore-db</code> options are applied, and
            such statements are always logged. (Bug #11829838, Bug
            #60188)
          </p><p><b>Row-based format. </b>
              Tells the server not to log updates to any tables in the
              database <em class="replaceable"><code>db_name</code></em>. The current
              database has no effect.
            </p><p>
            When using statement-based logging, the following example
            does not work as you might expect. Suppose that the server
            is started with
            <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db=sales</code></a> and
            you issue the following statements:
          </p><pre data-lang="sql" class="programlisting">USE prices;
UPDATE sales.january SET amount=amount+1000;</pre><p>
            The <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement
            <span class="emphasis"><em>is</em></span> logged in such a case because
            <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a> applies
            only to the default database (determined by the
            <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement). Because the
            <code class="literal">sales</code> database was specified explicitly
            in the statement, the statement has not been filtered.
            However, when using row-based logging, the
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement's
            effects are <span class="emphasis"><em>not</em></span> written to the binary
            log, which means that no changes to the
            <code class="literal">sales.january</code> table are logged; in this
            instance,
            <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db=sales</code></a>
            causes <span class="emphasis"><em>all</em></span> changes made to tables in
            the master's copy of the <code class="literal">sales</code>
            database to be ignored for purposes of binary logging.
          </p><p>
            To specify more than one database to ignore, use this option
            multiple times, once for each database. Because database
            names can contain commas, the list will be treated as the
            name of a single database if you supply a comma-separated
            list.
          </p><p>
            You should not use this option if you are using
            cross-database updates and you do not want these updates to
            be logged.
</p></li></ul>
</div>
<p><a name="replication-optvars-binlog-checksums"></a><b>Checksum options. </b>
          MySQL supports reading and writing of binary log checksums.
          These are enabled using the two options listed here:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_binlog-checksum"></a>
            <a class="indexterm" name="idm46444266605664"></a>

            <a class="indexterm" name="idm46444266604176"></a>

            <a class="link" href="replication.html#option_mysqld_binlog-checksum"><code class="option">--binlog-checksum={NONE|CRC32}</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog-checksum"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-checksum=type</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">CRC32</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">NONE</code></p><p class="valid-value"><code class="literal">CRC32</code></p></td>
</tr></tbody></table>
</div>
<p>
            Enabling this option causes the master to write checksums
            for events written to the binary log. Set to
            <code class="literal">NONE</code> to disable, or the name of the
            algorithm to be used for generating checksums; currently,
            only CRC32 checksums are supported, and CRC32 is the
            default. You cannot change the setting for this option
            within a transaction.
</p></li></ul>
</div>
<p>
        To control reading of checksums by the slave (from the relay
        log), use the
        <a class="link" href="replication.html#option_mysqld_slave-sql-verify-checksum"><code class="option">--slave-sql-verify-checksum</code></a>
        option.
      </p><p><b>Testing and debugging options. </b>
          The following binary log options are used in replication
          testing and debugging. They are not intended for use in normal
          operations.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="option_mysqld_max-binlog-dump-events"></a>
            <a class="indexterm" name="idm46444266575712"></a>

            <a class="indexterm" name="idm46444266574256"></a>

            <a class="link" href="replication.html#option_mysqld_max-binlog-dump-events"><code class="option">--max-binlog-dump-events=<em class="replaceable"><code>N</code></em></code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max-binlog-dump-events"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-binlog-dump-events=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr></tbody></table>
</div>
<p>
            This option is used internally by the MySQL test suite for
            replication testing and debugging.
          </p></li><li class="listitem"><p><a name="option_mysqld_sporadic-binlog-dump-fail"></a>
            <a class="indexterm" name="idm46444266554944"></a>

            <a class="indexterm" name="idm46444266553488"></a>

            <a class="link" href="replication.html#option_mysqld_sporadic-binlog-dump-fail"><code class="option">--sporadic-binlog-dump-fail</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sporadic-binlog-dump-fail"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--sporadic-binlog-dump-fail[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            This option is used internally by the MySQL test suite for
            replication testing and debugging.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-sysvars-binlog"></a>System Variables Used with Binary Logging</h5>

</div>

</div>

</div>
<p>
        The following list describes system variables for controlling
        binary logging. They can be set at server startup and some of
        them can be changed at runtime using
        <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>.
        Server options used to control binary logging are listed earlier
        in this section.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="sysvar_binlog_cache_size"></a>
            <a class="indexterm" name="idm46444266530848"></a>

            <a class="indexterm" name="idm46444266529808"></a>

            <a class="link" href="replication.html#sysvar_binlog_cache_size"><code class="literal">binlog_cache_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_cache_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-cache-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_cache_size">binlog_cache_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">32768</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">4096</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The size of the memory buffer to hold changes to the binary
            log during a transaction. When binary logging is enabled on
            the server (with the
            <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> system variable set
            to ON), a binary log cache is allocated for each client if
            the server supports any transactional storage engines. If
            the data for the transaction exceeds the space in the memory
            buffer, the excess data is stored in a temporary file. When
            binary log encryption is active on the server, the memory
            buffer is not encrypted, but (from MySQL 8.0.17) any
            temporary file used to hold the binary log cache is
            encrypted. After each transaction is committed, the binary
            log cache is reset by clearing the memory buffer and
            truncating the temporary file if used.
          </p><p>
            If you often use large transactions, you can increase this
            cache size to get better performance by reducing or
            eliminating the need to write to temporary files. The
            <a class="link" href="server-administration.html#statvar_Binlog_cache_use"><code class="literal">Binlog_cache_use</code></a> and
            <a class="link" href="server-administration.html#statvar_Binlog_cache_disk_use"><code class="literal">Binlog_cache_disk_use</code></a>
            status variables can be useful for tuning the size of this
            variable. See <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
          </p><p>
            <code class="literal">binlog_cache_size</code> sets the size for the
            transaction cache only; the size of the statement cache is
            governed by the
            <a class="link" href="replication.html#sysvar_binlog_stmt_cache_size"><code class="literal">binlog_stmt_cache_size</code></a>
            system variable.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_checksum"></a>
            <a class="indexterm" name="idm46444266479824"></a>

            <a class="indexterm" name="idm46444266478816"></a>

            <a class="link" href="replication.html#sysvar_binlog_checksum"><code class="literal">binlog_checksum</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_checksum"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-checksum=name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_checksum">binlog_checksum</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">CRC32</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">NONE</code></p><p class="valid-value"><code class="literal">CRC32</code></p></td>
</tr></tbody></table>
</div>
<p>
            When enabled, this variable causes the master to write a
            checksum for each event in the binary log.
            <code class="literal">binlog_checksum</code> supports the values
            <code class="literal">NONE</code> (disabled) and
            <code class="literal">CRC32</code>. The default is
            <code class="literal">CRC32</code>. When
            <code class="literal">binlog_checksum</code> is disabled (value
            <code class="literal">NONE</code>), the server verifies that it is
            writing only complete events to the binary log by writing
            and checking the event length (rather than a checksum) for
            each event.
          </p><p>
            Setting this variable on the master to a value unrecognized
            by the slave causes the slave to set its own
            <code class="literal">binlog_checksum</code> value to
            <code class="literal">NONE</code>, and to stop replication with an
            error. If backward compatibility with older slaves is a
            concern, you may want to set the value explicitly to
            <code class="literal">NONE</code>.
          </p><p>
            Changing the value of <code class="literal">binlog_checksum</code>
            causes the binary log to be rotated, because checksums must
            be written for an entire binary log file, and never for only
            part of one. You cannot change the value of
            <code class="literal">binlog_checksum</code> within a transaction.
          </p><p>
            When binary log transaction compression is enabled using the
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>
            system variable, checksums are not written for individual
            events in a compressed transaction payload. Instead a
            checksum is written for the GTID event, and a checksum for
            the compressed <code class="literal">Transaction_payload_event</code>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_direct_non_transactional_updates"></a>
            <a class="indexterm" name="idm46444266430112"></a>

            <a class="indexterm" name="idm46444266429072"></a>

            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_direct_non_transactional_updates"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-direct-non-transactional-updates[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates">binlog_direct_non_transactional_updates</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Due to concurrency issues, a slave can become inconsistent
            when a transaction contains updates to both transactional
            and nontransactional tables. MySQL tries to preserve
            causality among these statements by writing nontransactional
            statements to the transaction cache, which is flushed upon
            commit. However, problems arise when modifications done to
            nontransactional tables on behalf of a transaction become
            immediately visible to other connections because these
            changes may not be written immediately into the binary log.
          </p><p>
            The
            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            variable offers one possible workaround to this issue. By
            default, this variable is disabled. Enabling
            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            causes updates to nontransactional tables to be written
            directly to the binary log, rather than to the transaction
            cache.
          </p><p>
            As of MySQL 8.0.14, setting the session value of this system
            variable is a restricted operation. The session user must
            have privileges sufficient to set restricted session
            variables. See <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            <span class="emphasis"><em><a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            works only for statements that are replicated using the
            statement-based binary logging format</em></span>; that is,
            it works only when the value of
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is
            <code class="literal">STATEMENT</code>, or when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is
            <code class="literal">MIXED</code> and a given statement is being
            replicated using the statement-based format. This variable
            has no effect when the binary log format is
            <code class="literal">ROW</code>, or when
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
            <code class="literal">MIXED</code> and a given statement is replicated
            using the row-based format.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
              Before enabling this variable, you must make certain that
              there are no dependencies between transactional and
              nontransactional tables; an example of such a dependency
              would be the statement <code class="literal">INSERT INTO myisam_table
              SELECT * FROM innodb_table</code>. Otherwise, such
              statements are likely to cause the slave to diverge from
              the master.
</p>
</div>
<p>
            This variable has no effect when the binary log format is
            <code class="literal">ROW</code> or <code class="literal">MIXED</code>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_encryption"></a>
            <a class="indexterm" name="idm46444266379040"></a>

            <a class="indexterm" name="idm46444266378000"></a>

            <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_encryption"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-encryption[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.14</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_encryption">binlog_encryption</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Enables encryption for binary log files and relay log files
            on this server. <code class="literal">OFF</code> is the default.
            <code class="literal">ON</code> sets encryption on for binary log
            files and relay log files. Binary logging does not need to
            be enabled on the server to enable encryption, so you can
            encrypt the relay log files on a slave that has no binary
            log. To use encryption, a keyring plugin must be installed
            and configured to supply MySQL Server's keyring service. For
            instructions to do this, see <a class="xref" href="security.html#keyring" title="6.4.4 The MySQL Keyring">Section 6.4.4, “The MySQL Keyring”</a>. Any
            supported keyring plugin can be used to store binary log
            encryption keys.
          </p><p>
            When you first start the server with binary log encryption
            enabled, a new binary log encryption key is generated before
            the binary log and relay logs are initialized. This key is
            used to encrypt a file password for each binary log file (if
            the server has binary logging enabled) and relay log file
            (if the server has replication channels), and further keys
            generated from the file passwords are used to encrypt the
            data in the files. Relay log files are encrypted for all
            channels, including Group Replication applier channels and
            new channels that are created after encryption is activated.
            The binary log index file and relay log index file are never
            encrypted.
          </p><p>
            If you activate encryption while the server is running, a
            new binary log encryption key is generated at that time. The
            exception is if encryption was active previously on the
            server and was then disabled, in which case the binary log
            encryption key that was in use before is used again. The
            binary log file and relay log files are rotated immediately,
            and file passwords for the new files and all subsequent
            binary log files and relay log files are encrypted using
            this binary log encryption key. Existing binary log files
            and relay log files still present on the server are not
            automatically encrypted, but you can purge them if they are
            no longer needed.
          </p><p>
            If you deactivate encryption by changing the
            <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a> system
            variable to <code class="literal">OFF</code>, the binary log file and
            relay log files are rotated immediately and all subsequent
            logging is unencrypted. Previously encrypted files are not
            automatically decrypted, but the server is still able to
            read them. The <code class="literal">BINLOG_ENCRYPTION_ADMIN</code>
            privilege (or the deprecated
            <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a> privilege) is required
            to activate or deactivate encryption while the server is
            running. Group Replication applier channels are not included
            in the relay log rotation request, so unencrypted logging
            for these channels does not start until their logs are
            rotated in normal use.
          </p><p>
            For more information on binary log file and relay log file
            encryption, see
            <a class="xref" href="replication.html#replication-binlog-encryption" title="17.3.2 Encrypting Binary Log Files and Relay Log Files">Section 17.3.2, “Encrypting Binary Log Files and Relay Log Files”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_error_action"></a>
            <a class="indexterm" name="idm46444266332112"></a>

            <a class="indexterm" name="idm46444266331072"></a>

            <a class="link" href="replication.html#sysvar_binlog_error_action"><code class="literal">binlog_error_action</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_error_action"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-error-action[=value]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_error_action">binlog_error_action</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ABORT_SERVER</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">IGNORE_ERROR</code></p><p class="valid-value"><code class="literal">ABORT_SERVER</code></p></td>
</tr></tbody></table>
</div>
<p>
            Controls what happens when the server encounters an error
            such as not being able to write to, flush or synchronize the
            binary log, which can cause the master's binary log to
            become inconsistent and replication slaves to lose
            synchronization.
          </p><p>
            This variable defaults to <code class="literal">ABORT_SERVER</code>,
            which makes the server halt logging and shut down whenever
            it encounters such an error with the binary log. On restart,
            recovery proceeds as in the case of an unexpected server
            halt (see
            <a class="xref" href="replication.html#replication-solutions-unexpected-slave-halt" title="17.4.2 Handling an Unexpected Halt of a Replication Slave">Section 17.4.2, “Handling an Unexpected Halt of a Replication Slave”</a>).
          </p><p>
            When <code class="literal">binlog_error_action</code> is set to
            <code class="literal">IGNORE_ERROR</code>, if the server encounters
            such an error it continues the ongoing transaction, logs the
            error then halts logging, and continues performing updates.
            To resume binary logging
            <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> must be enabled
            again, which requires a server restart. This setting
            provides backward compatibility with older versions of
            MySQL.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_expire_logs_seconds"></a>
            <a class="indexterm" name="idm46444266288816"></a>

            <a class="indexterm" name="idm46444266287776"></a>

            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_expire_logs_seconds"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-expire-logs-seconds=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds">binlog_expire_logs_seconds</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">2592000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            Sets the binary log expiration period in seconds. After
            their expiration period ends, binary log files can be
            automatically removed. Possible removals happen at startup
            and when the binary log is flushed. Log flushing occurs as
            indicated in <a class="xref" href="server-administration.html#server-logs" title="5.4 MySQL Server Logs">Section 5.4, “MySQL Server Logs”</a>.
          </p><p>
            The default binary log expiration period is 2592000 seconds,
            which equals 30 days (30*24*60*60 seconds). The default
            applies if neither
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            nor the deprecated system variable
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> has a
            value set at startup. If a non-zero value for one of the
            variables
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            or <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> is set
            at startup, this value is used as the binary log expiration
            period. If a non-zero value for both of those variables is
            set at startup, the value for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is used as the binary log expiration period, and the value
            for <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> is
            ignored with a warning message.
          </p><p>
            To disable automatic purging of the binary log, specify a
            value of 0 explicitly for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>,
            and do not specify a value for
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a>. For
            compatibility with earlier releases, automatic purging is
            also disabled if you specify a value of 0 explicitly for
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> and do not
            specify a value for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>.
            In that case, the default for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is not applied.
          </p><p>
            To remove binary log files manually, use the
            <a class="link" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement"><code class="literal">PURGE BINARY LOGS</code></a> statement.
            See <a class="xref" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement">Section 13.4.1.1, “PURGE BINARY LOGS Statement”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_format"></a>
            <a class="indexterm" name="idm46444266230624"></a>

            <a class="indexterm" name="idm46444266229568"></a>

            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_format"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-format=format</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_format">binlog_format</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ROW</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">ROW</code></p><p class="valid-value"><code class="literal">STATEMENT</code></p><p class="valid-value"><code class="literal">MIXED</code></p></td>
</tr></tbody></table>
</div>
<p>
            This variable sets the binary logging format, and can be any
            one of <code class="literal">STATEMENT</code>, <code class="literal">ROW</code>,
            or <code class="literal">MIXED</code>. See
            <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
          </p><p>
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> can be set at
            startup or at runtime, except that under some conditions,
            changing this variable at runtime is not possible or causes
            replication to fail, as described later.
          </p><p>
            The default is <code class="literal">ROW</code>.
            <span class="emphasis"><em>Exception</em></span>: In NDB Cluster, the default
            is <code class="literal">MIXED</code>; statement-based replication is
            not supported for NDB Cluster.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have privileges
            sufficient to set restricted session variables. See
            <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            The rules governing when changes to this variable take
            effect and how long the effect lasts are the same as for
            other MySQL server system variables. For more information,
            see <a class="xref" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment">Section 13.7.6.1, “SET Syntax for Variable Assignment”</a>.
          </p><p>
            When <code class="literal">MIXED</code> is specified, statement-based
            replication is used, except for cases where only row-based
            replication is guaranteed to lead to proper results. For
            example, this happens when statements contain user-defined
            functions (UDF) or the <a class="link" href="functions.html#function_uuid"><code class="literal">UUID()</code></a>
            function.
          </p><p>
            For details of how stored programs (stored procedures and
            functions, triggers, and events) are handled when each
            binary logging format is set, see
            <a class="xref" href="stored-objects.html#stored-programs-logging" title="24.7 Stored Program Binary Logging">Section 24.7, “Stored Program Binary Logging”</a>.
          </p><p>
            There are exceptions when you cannot switch the replication
            format at runtime:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                The replication format cannot be changed from within a
                stored function or a trigger.
              </p></li><li class="listitem"><p>
                If a session has open temporary tables, the replication
                format cannot be changed for the session (<code class="literal">SET
                @@SESSION.binlog_format</code>).
              </p></li><li class="listitem"><p>
                If any replication channel has open temporary tables,
                the replication format cannot be changed globally
                (<code class="literal">SET @@GLOBAL.binlog_format</code> or
                <code class="literal">SET @@PERSIST.binlog_format</code>).
              </p></li><li class="listitem"><p>
                If any replication channel applier thread is currently
                running, the replication format cannot be changed
                globally (<code class="literal">SET @@GLOBAL.binlog_format</code>
                or <code class="literal">SET @@PERSIST.binlog_format</code>).
</p></li></ul>
</div>
<p>
            Trying to switch the replication format in any of these
            cases (or attempting to set the current replication format)
            results in an error. You can, however, use
            <code class="literal">PERSIST_ONLY</code> (<code class="literal">SET
            @@PERSIST_ONLY.binlog_format</code>) to change the
            replication format at any time, because this action does not
            modify the runtime global system variable value, and takes
            effect only after a server restart.
          </p><p>
            Switching the replication format at runtime is not
            recommended when any temporary tables exist, because
            temporary tables are logged only when using statement-based
            replication, whereas with row-based replication and mixed
            replication, they are not logged.
          </p><p>
            Changing the logging format on a replication master does not
            cause a replication slave to change its logging format to
            match. Switching the replication format while replication is
            ongoing can cause issues if a replication slave has binary
            logging enabled, and the change results in the slave using
            <code class="literal">STATEMENT</code> format logging while the master
            is using <code class="literal">ROW</code> or <code class="literal">MIXED</code>
            format logging. A replication slave is not able to convert
            binary log entries received in <code class="literal">ROW</code>
            logging format to <code class="literal">STATEMENT</code> format for
            use in its own binary log, so this situation can cause
            replication to fail. For more information, see
            <a class="xref" href="server-administration.html#binary-log-setting" title="5.4.4.2 Setting The Binary Log Format">Section 5.4.4.2, “Setting The Binary Log Format”</a>.
          </p><p>
            The binary log format affects the behavior of the following
            server options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a>
</p></li></ul>
</div>
<p>
            These effects are discussed in detail in the descriptions of
            the individual options.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_group_commit_sync_delay"></a>
            <a class="indexterm" name="idm46444266153808"></a>

            <a class="indexterm" name="idm46444266152768"></a>

            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_group_commit_sync_delay"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-group-commit-sync-delay=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay">binlog_group_commit_sync_delay</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1000000</code></td>
</tr></tbody></table>
</div>
<p>
            Controls how many microseconds the binary log commit waits
            before synchronizing the binary log file to disk. By default
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            is set to 0, meaning that there is no delay. Setting
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            to a microsecond delay enables more transactions to be
            synchronized together to disk at once, reducing the overall
            time to commit a group of transactions because the larger
            groups require fewer time units per group.
          </p><p>
            When <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=0</code></a> or
            <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a> is set, the
            delay specified by
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            is applied for every binary log commit group before
            synchronization (or in the case of
            <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=0</code></a>, before
            proceeding). When
            <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog</code></a> is set to a
            value <span class="emphasis"><em>n</em></span> greater than 1, the delay is
            applied after every <span class="emphasis"><em>n</em></span> binary log commit
            groups.
          </p><p>
            Setting
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            can increase the number of parallel committing transactions
            on any server that has (or might have after a failover) a
            replication slave, and therefore can increase parallel
            execution on the replication slaves. To benefit from this
            effect, the slave servers must have
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type=LOGICAL_CLOCK</code></a>
            set, and the effect is more significant when
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking=COMMIT_ORDER</code></a>
            is also set. It is important to take into account both the
            master's throughput and the slaves' throughput when you are
            tuning the setting for
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>.
          </p><p>
            Setting
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            can also reduce the number of <code class="literal">fsync()</code>
            calls to the binary log on any server (master or slave) that
            has a binary log.
          </p><p>
            Note that setting
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            increases the latency of transactions on the server, which
            might affect client applications. Also, on highly concurrent
            workloads, it is possible for the delay to increase
            contention and therefore reduce throughput. Typically, the
            benefits of setting a delay outweigh the drawbacks, but
            tuning should always be carried out to determine the optimal
            setting.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_group_commit_sync_no_delay_count"></a>
            <a class="indexterm" name="idm46444266092992"></a>

            <a class="indexterm" name="idm46444266091904"></a>

            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_no_delay_count"><code class="literal">binlog_group_commit_sync_no_delay_count</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_group_commit_sync_no_delay_count"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-group-commit-sync-no-delay-count=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_group_commit_sync_no_delay_count">binlog_group_commit_sync_no_delay_count</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1000000</code></td>
</tr></tbody></table>
</div>
<p>
            The maximum number of transactions to wait for before
            aborting the current delay as specified by
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>.
            If
            <a class="link" href="replication.html#sysvar_binlog_group_commit_sync_delay"><code class="literal">binlog_group_commit_sync_delay</code></a>
            is set to 0, then this option has no effect.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_max_flush_queue_time"></a>
            <a class="indexterm" name="idm46444266051056"></a>

            <a class="indexterm" name="idm46444266049952"></a>

            <a class="link" href="replication.html#sysvar_binlog_max_flush_queue_time"><code class="literal">binlog_max_flush_queue_time</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_max_flush_queue_time"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-max-flush-queue-time=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_max_flush_queue_time">binlog_max_flush_queue_time</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">100000</code></td>
</tr></tbody></table>
</div>
<p>
            <code class="literal">binlog_max_flush_queue_time</code> is
            deprecated, and is marked for eventual removal in a future
            MySQL release. Formerly, this system variable controlled the
            time in microseconds to continue reading transactions from
            the flush queue before proceeding with group commit. It no
            longer has any effect.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_order_commits"></a>
            <a class="indexterm" name="idm46444266008224"></a>

            <a class="indexterm" name="idm46444266007184"></a>

            <a class="link" href="replication.html#sysvar_binlog_order_commits"><code class="literal">binlog_order_commits</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_order_commits"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-order-commits[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_order_commits">binlog_order_commits</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            When this variable is enabled on a replication master (which
            is the default), transaction commit instructions issued to
            storage engines are serialized on a single thread, so that
            transactions are always committed in the same order as they
            are written to the binary log. Disabling this variable
            permits transaction commit instructions to be issued using
            multiple threads. Used in combination with binary log group
            commit, this prevents the commit rate of a single
            transaction being a bottleneck to throughput, and might
            therefore produce a performance improvement.
          </p><p>
            Transactions are written to the binary log at the point when
            all the storage engines involved have confirmed that the
            transaction is prepared to commit. The binary log group
            commit logic then commits a group of transactions after
            their binary log write has taken place. When
            <a class="link" href="replication.html#sysvar_binlog_order_commits"><code class="literal">binlog_order_commits</code></a> is
            disabled, because multiple threads are used for this
            process, transactions in a commit group might be committed
            in a different order from their order in the binary log.
            (Transactions from a single client always commit in
            chronological order.) In many cases this does not matter, as
            operations carried out in separate transactions should
            produce consistent results, and if that is not the case, a
            single transaction ought to be used instead.
          </p><p>
            If you want to ensure that the transaction history on the
            master and on a multithreaded replication slave remains
            identical, set
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            on the replication slave.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_rotate_encryption_master_key_at_startup"></a>
            <a class="indexterm" name="idm46444265970144"></a>

            <a class="indexterm" name="idm46444265969024"></a>

            <a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup"><code class="literal">binlog_rotate_encryption_master_key_at_startup</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_rotate_encryption_master_key_at_startup"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-rotate-encryption-master-key-at-startup[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.14</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup">binlog_rotate_encryption_master_key_at_startup</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Specifies whether or not the binary log master key is
            rotated at server startup. The binary log master key is the
            binary log encryption key that is used to encrypt file
            passwords for the binary log files and relay log files on
            the server. When a server is started for the first time with
            binary log encryption enabled
            (<a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption=ON</code></a>), a
            new binary log encryption key is generated and used as the
            binary log master key. If the
            <a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup"><code class="literal">binlog_rotate_encryption_master_key_at_startup</code></a>
            system variable is also set to <code class="literal">ON</code>,
            whenever the server is restarted, a further binary log
            encryption key is generated and used as the binary log
            master key for all subsequent binary log files and relay log
            files. If the
            <a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup"><code class="literal">binlog_rotate_encryption_master_key_at_startup</code></a>
            system variable is set to <code class="literal">OFF</code>, which is
            the default, the existing binary log master key is used
            again after the server restarts. For more information on
            binary log encryption keys and the binary log master key,
            see <a class="xref" href="replication.html#replication-binlog-encryption" title="17.3.2 Encrypting Binary Log Files and Relay Log Files">Section 17.3.2, “Encrypting Binary Log Files and Relay Log Files”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_row_event_max_size"></a>
            <a class="indexterm" name="idm46444265927296"></a>

            <a class="indexterm" name="idm46444265926192"></a>

            <a class="link" href="replication.html#sysvar_binlog_row_event_max_size"><code class="literal">binlog_row_event_max_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog-row-event-max-size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-row-event-max-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span> (≥ 8.0.14)</td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_event_max_size">binlog_row_event_max_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span> (≥ 8.0.14)</td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span> (≥ 8.0.14)</td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span> (≥ 8.0.14)</td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">8192</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">256</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            When row-based binary logging is used, this setting is a
            soft limit on the maximum size of a row-based binary log
            event, in bytes. Where possible, rows stored in the binary
            log are grouped into events with a size not exceeding the
            value of this setting. If an event cannot be split, the
            maximum size can be exceeded. The value must be (or else
            gets rounded down to) a multiple of 256. The default is 8192
            bytes.
          </p><p>
            This global system variable is read-only and can be set only
            at server startup. Its value can therefore only be modified
            by using the <code class="literal">PERSIST_ONLY</code> keyword or the
            <code class="literal">@@persist_only</code> qualifier with the
            <a class="link" href="data-types.html#set" title="11.3.6 The SET Type"><code class="literal">SET</code></a> statement.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_row_image"></a>
            <a class="indexterm" name="idm46444265880336"></a>

            <a class="indexterm" name="idm46444265879280"></a>

            <a class="link" href="replication.html#sysvar_binlog_row_image"><code class="literal">binlog_row_image</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_row_image"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-row-image=image_type</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_image">binlog_row_image</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">full</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">full</code> (Log all columns)</p><p class="valid-value"><code class="literal">minimal</code> (Log only changed columns, and columns needed to identify rows)</p><p class="valid-value"><code class="literal">noblob</code> (Log all columns, except for unneeded BLOB and TEXT columns)</p></td>
</tr></tbody></table>
</div>
<p>
            For MySQL row-based replication, this variable determines
            how row images are written to the binary log.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have privileges
            sufficient to set restricted session variables. See
            <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            In MySQL row-based replication, each row change event
            contains two images, a <span class="quote">“<span class="quote">before</span>”</span> image whose
            columns are matched against when searching for the row to be
            updated, and an <span class="quote">“<span class="quote">after</span>”</span> image containing the
            changes. Normally, MySQL logs full rows (that is, all
            columns) for both the before and after images. However, it
            is not strictly necessary to include every column in both
            images, and we can often save disk, memory, and network
            usage by logging only those columns which are actually
            required.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              When deleting a row, only the before image is logged,
              since there are no changed values to propagate following
              the deletion. When inserting a row, only the after image
              is logged, since there is no existing row to be matched.
              Only when updating a row are both the before and after
              images required, and both written to the binary log.
</p>
</div>
<p>
            For the before image, it is necessary only that the minimum
            set of columns required to uniquely identify rows is logged.
            If the table containing the row has a primary key, then only
            the primary key column or columns are written to the binary
            log. Otherwise, if the table has a unique key all of whose
            columns are <code class="literal">NOT NULL</code>, then only the
            columns in the unique key need be logged. (If the table has
            neither a primary key nor a unique key without any
            <code class="literal">NULL</code> columns, then all columns must be
            used in the before image, and logged.) In the after image,
            it is necessary to log only the columns which have actually
            changed.
          </p><p>
            You can cause the server to log full or minimal rows using
            the <code class="literal">binlog_row_image</code> system variable.
            This variable actually takes one of three possible values,
            as shown in the following list:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">full</code>: Log all columns in both the
                before image and the after image.
              </p></li><li class="listitem"><p>
                <code class="literal">minimal</code>: Log only those columns in
                the before image that are required to identify the row
                to be changed; log only those columns in the after image
                where a value was specified by the SQL statement, or
                generated by auto-increment.
              </p></li><li class="listitem"><p>
                <code class="literal">noblob</code>: Log all columns (same as
                <code class="literal">full</code>), except for
                <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> and
                <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> columns that are not
                required to identify rows, or that have not changed.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
              This variable is not supported by NDB Cluster; setting it
              has no effect on the logging of
              <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a> tables.
</p>
</div>
<p>
            The default value is <code class="literal">full</code>.
          </p><p>
            When using <code class="literal">minimal</code> or
            <code class="literal">noblob</code>, deletes and updates are
            guaranteed to work correctly for a given table if and only
            if the following conditions are true for both the source and
            destination tables:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                All columns must be present and in the same order; each
                column must use the same data type as its counterpart in
                the other table.
              </p></li><li class="listitem"><p>
                The tables must have identical primary key definitions.
</p></li></ul>
</div>
<p>
            (In other words, the tables must be identical with the
            possible exception of indexes that are not part of the
            tables' primary keys.)
          </p><p>
            If these conditions are not met, it is possible that the
            primary key column values in the destination table may prove
            insufficient to provide a unique match for a delete or
            update. In this event, no warning or error is issued; the
            master and slave silently diverge, thus breaking
            consistency.
          </p><p>
            Setting this variable has no effect when the binary logging
            format is <code class="literal">STATEMENT</code>. When
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is
            <code class="literal">MIXED</code>, the setting for
            <code class="literal">binlog_row_image</code> is applied to changes
            that are logged using row-based format, but this setting has
            no effect on changes logged as statements.
          </p><p>
            Setting <code class="literal">binlog_row_image</code> on either the
            global or session level does not cause an implicit commit;
            this means that this variable can be changed while a
            transaction is in progress without affecting the
            transaction.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_row_metadata"></a>
            <a class="indexterm" name="idm46444265810128"></a>

            <a class="indexterm" name="idm46444265809088"></a>

            <a class="link" href="replication.html#sysvar_binlog_row_metadata"><code class="literal">binlog_row_metadata</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_row_metadata"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-row-metadata=metadata_type</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_metadata">binlog_row_metadata</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">MINIMAL</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">FULL</code> (All metadata is included)</p><p class="valid-value"><code class="literal">MINIMAL</code> (Limit included metadata)</p></td>
</tr></tbody></table>
</div>
<p>
            Configures the amount of table metadata added to the binary
            log when using row-based logging. When set to
            <code class="literal">MINIMAL</code>, the default, only metadata
            related to <code class="literal">SIGNED</code> flags, column character
            set and geometry types are logged. When set to
            <code class="literal">FULL</code> complete metadata for tables is
            logged, such as column name,
            <a class="link" href="data-types.html#enum" title="11.3.5 The ENUM Type"><code class="literal">ENUM</code></a> or
            <code class="literal">SET</code> string values, <code class="literal">PRIMARY
            KEY</code> information, and so on.
          </p><p>
            The extended metadata serves the following purposes:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                Slaves use the metadata to transfer data when its table
                structure is different from the master's.
              </p></li><li class="listitem"><p>
                External software can use the metadata to decode row
                events and store the data into external databases, such
                as a data warehouse.
</p></li></ul>
</div>
</li><li class="listitem"><p><a name="sysvar_binlog_row_value_options"></a>
            <a class="indexterm" name="idm46444265764480"></a>

            <a class="indexterm" name="idm46444265763376"></a>

            <a class="link" href="replication.html#sysvar_binlog_row_value_options"><code class="literal">binlog_row_value_options</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_row_value_options"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-row-value-options=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_row_value_options">binlog_row_value_options</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Set</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">''</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><code class="literal">PARTIAL_JSON</code></td>
</tr></tbody></table>
</div>
<p>
            When set to <code class="literal">PARTIAL_JSON</code>, this enables
            use of a space-efficient binary log format for updates that
            modify only a small portion of a JSON document, which causes
            row-based replication to write only the modified parts of
            the JSON document to the after-image for the update in the
            binary log (rather than writing the full document). This
            works for an <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement
            which modifies a JSON column using any sequence of
            <a class="link" href="functions.html#function_json-set"><code class="literal">JSON_SET()</code></a>,
            <a class="link" href="functions.html#function_json-replace"><code class="literal">JSON_REPLACE()</code></a>, and
            <a class="link" href="functions.html#function_json-remove"><code class="literal">JSON_REMOVE()</code></a>. If the
            modification requires more space than the full document, or
            if the server is unable to generate a partial update, the
            full document is used instead.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have privileges
            sufficient to set restricted session variables. See
            <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            <code class="literal">PARTIAL_JSON</code> is the only supported value;
            to unset <code class="literal">binlog_row_value_options</code>, set
            its value to the empty string.
          </p><p>
            <code class="literal">binlog_row_value_options=PARTIAL_JSON</code>
            takes effect only when binary logging is enabled and
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
            <code class="literal">ROW</code> or <code class="literal">MIXED</code>.
            Statement-based replication <span class="emphasis"><em>always</em></span> logs
            only the modified parts of the JSON document, regardless of
            any value set for
            <code class="literal">binlog_row_value_options</code>. To maximize the
            amount of space saved, use
            <a class="link" href="replication.html#sysvar_binlog_row_image"><code class="literal">binlog_row_image=NOBLOB</code></a> or
            <code class="literal">binlog_row_image=MINIMAL</code> together with
            this option. <code class="literal">binlog_row_image=FULL</code> saves
            less space than either of these, since the full JSON
            document is stored in the before-image, and the partial
            update is stored only in the after-image.
          </p><p>
            <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output includes partial JSON
            updates in the form of events encoded as base-64 strings
            using <a class="link" href="sql-statements.html#binlog" title="13.7.8.1 BINLOG Statement"><code class="literal">BINLOG</code></a> statements. If
            the <a class="link" href="programs.html#option_mysqlbinlog_verbose"><code class="option">--verbose</code></a> option is
            specified, <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> displays the
            partial JSON updates as readable JSON using pseudo-SQL
            statements.
          </p><p>
            MySQL Replication generates an error if a modification
            cannot be applied to the JSON document on the slave. This
            includes a failure to find the path. Be aware that, even
            with this and other safety checks, if a JSON document on a
            slave has diverged from that on the master and a partial
            update is applied, it remains theoretically possible to
            produce a valid but unexpected JSON document on the slave.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_rows_query_log_events"></a>
            <a class="indexterm" name="idm46444265703872"></a>

            <a class="indexterm" name="idm46444265702768"></a>

            <code class="literal">binlog_rows_query_log_events</code>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_rows_query_log_events"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-rows-query-log-events[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_rows_query_log_events">binlog_rows_query_log_events</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            This system variable affects row-based logging only. When
            enabled, it causes the server to write informational log
            events such as row query log events into its binary log.
            This information can be used for debugging and related
            purposes, such as obtaining the original query issued on the
            master when it cannot be reconstructed from the row updates.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have privileges
            sufficient to set restricted session variables. See
            <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            These informational events are normally ignored by MySQL
            programs reading the binary log and so cause no issues when
            replicating or restoring from backup. To view them, increase
            the verbosity level by using mysqlbinlog's
            <a class="link" href="programs.html#option_mysqlbinlog_verbose"><code class="option">--verbose</code></a> option twice,
            either as <code class="option">-vv</code> or <code class="option">--verbose
            --verbose</code>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_stmt_cache_size"></a>
            <a class="indexterm" name="idm46444265667072"></a>

            <a class="indexterm" name="idm46444265666032"></a>

            <a class="link" href="replication.html#sysvar_binlog_stmt_cache_size"><code class="literal">binlog_stmt_cache_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_stmt_cache_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-stmt-cache-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_stmt_cache_size">binlog_stmt_cache_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">32768</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">4096</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (64-bit platforms)</td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span> (32-bit platforms)</td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            The size of the memory buffer for the binary log to hold
            nontransactional statements issued during a transaction.
            When binary logging is enabled on the server (with the
            <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> system variable set
            to ON), separate binary log transaction and statement caches
            are allocated for each client if the server supports any
            transactional storage engines. If the data for the
            nontransactional statements used in the transaction exceeds
            the space in the memory buffer, the excess data is stored in
            a temporary file. When binary log encryption is active on
            the server, the memory buffer is not encrypted, but (from
            MySQL 8.0.17) any temporary file used to hold the binary log
            cache is encrypted. After each transaction is committed, the
            binary log statement cache is reset by clearing the memory
            buffer and truncating the temporary file if used.
          </p><p>
            If you often use large nontransactional statements during
            transactions, you can increase this cache size to get better
            performance by reducing or eliminating the need to write to
            temporary files. The
            <a class="link" href="server-administration.html#statvar_Binlog_stmt_cache_use"><code class="literal">Binlog_stmt_cache_use</code></a> and
            <a class="link" href="server-administration.html#statvar_Binlog_stmt_cache_disk_use"><code class="literal">Binlog_stmt_cache_disk_use</code></a>
            status variables can be useful for tuning the size of this
            variable. See <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
          </p><p>
            The <a class="link" href="replication.html#sysvar_binlog_cache_size"><code class="literal">binlog_cache_size</code></a>
            system variable sets the size for the transaction cache.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_transaction_compression"></a>
            <a class="indexterm" name="idm46444265616608"></a>

            <a class="indexterm" name="idm46444265615504"></a>

            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_transaction_compression"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-transaction-compression[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.20</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_compression">binlog_transaction_compression</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Enables compression for transactions that are written to
            binary log files on this server. <code class="literal">OFF</code> is
            the default. Use the
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression_level_zstd"><code class="literal">binlog_transaction_compression_level_zstd</code></a>
            system variable to set the level for the zstd algorithm that
            is used for compression.
          </p><p>
            When binary log transaction compression is enabled,
            transaction payloads are compressed and then written to the
            binary log file as a single event
            (<code class="literal">Transaction_payload_event</code>). Compressed
            transaction payloads remain in a compressed state while they
            are sent in the replication stream to replication slaves,
            other Group Replication group members, or clients such as
            <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, and are written to the relay
            log still in their compressed state. Binary log transaction
            compression therefore saves storage space both on the
            originator of the transaction and on the recipient (and for
            their backups), and saves network bandwidth when the
            transactions are sent between server instances.
          </p><p>
            For <code class="literal">binlog_transaction_compression=ON</code> to
            have a direct effect, binary logging must be enabled on the
            server. When a MySQL server instance has no binary log, if
            it is at a release from MySQL 8.0.20, it can receive,
            handle, and display compressed transaction payloads
            regardless of its value for
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>.
            Compressed transaction payloads received by such server
            instances are written in their compressed state to the relay
            log, so they benefit indirectly from compression carried out
            by other servers in the replication topology.
          </p><p>
            This system variable cannot be changed within the context of
            a transaction. Setting the session value of this system
            variable is a restricted operation. The session user must
            have privileges sufficient to set restricted session
            variables. See <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            For more information on binary log transaction compression,
            including details of what events are and are not compressed,
            and changes in behavior when transaction compression is in
            use, see
            <a class="xref" href="server-administration.html#binary-log-transaction-compression" title="5.4.4.5 Binary Log Transaction Compression">Section 5.4.4.5, “Binary Log Transaction Compression”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_transaction_compression_level_zstd"></a>
            <a class="indexterm" name="idm46444265569600"></a>

            <a class="indexterm" name="idm46444265568480"></a>

            <a class="link" href="replication.html#sysvar_binlog_transaction_compression_level_zstd"><code class="literal">binlog_transaction_compression_level_zstd</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_transaction_compression_level_zstd"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-transaction-compression-level-zstd=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Introduced</strong></span></td>
<td>8.0.20</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_compression_level_zstd">binlog_transaction_compression_level_zstd</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">3</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">22</code></td>
</tr></tbody></table>
</div>
<p>
            Sets the compression level for binary log transaction
            compression on this server, which is enabled by the
            <a class="link" href="replication.html#sysvar_binlog_transaction_compression"><code class="literal">binlog_transaction_compression</code></a>
            system variable. The value is an integer that determines the
            compression effort, from 1 (the lowest effort) to 22 (the
            highest effort). If you do not specify this system variable,
            the compression level is set to 3.
          </p><p>
            As the compression level increases, the data compression
            ratio increases, which reduces the storage space and network
            bandwidth required for the transaction payload. However, the
            effort required for data compression also increases, taking
            time and CPU and memory resources on the originating server.
            Increases in the compression effort do not have a linear
            relationship to increases in the data compression ratio.
          </p><p>
            This system variable cannot be changed within the context of
            a transaction. Setting the session value of this system
            variable is a restricted operation. The session user must
            have privileges sufficient to set restricted session
            variables. See <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_transaction_dependency_tracking"></a>
            <a class="indexterm" name="idm46444265523616"></a>

            <a class="indexterm" name="idm46444265522576"></a>

            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_transaction_dependency_tracking"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-transaction-dependency-tracking=value</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking">binlog_transaction_dependency_tracking</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">COMMIT_ORDER</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">COMMIT_ORDER</code></p><p class="valid-value"><code class="literal">WRITESET</code></p><p class="valid-value"><code class="literal">WRITESET_SESSION</code></p></td>
</tr></tbody></table>
</div>
<p>
            For a replication master that has multithreaded slaves
            (replication slaves on which
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> is
            set to a value greater than 0),
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            specifies the source of dependency information that the
            master records in the binary log to help slaves determine
            which transactions can be executed in parallel. The possible
            values are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">COMMIT_ORDER</code>: Dependency information
                is generated from the master's commit timestamps.
                This is the default.
              </p></li><li class="listitem"><p>
                <code class="literal">WRITESET</code>: Dependency information is
                generated from the master's write set, and any
                transactions that write different tuples can be
                parallelized.
              </p></li><li class="listitem"><p>
                <code class="literal">WRITESET_SESSION</code>: Dependency
                information is generated from the master's write
                set, and any transactions that write different tuples
                can be parallelized, with the exception that no two
                updates from the same session can be reordered.
</p></li></ul>
</div>
<p>
            <code class="literal">WRITESET</code> and
            <code class="literal">WRITESET_SESSION</code> modes do not deliver any
            transaction dependencies that are less optimized than those
            that would have been returned in
            <code class="literal">COMMIT_ORDER</code> mode. When you set
            <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code> as the value, the master
            uses <code class="literal">COMMIT_ORDER</code> mode for any
            transactions that have empty or partial write sets, for any
            transactions that update tables without primary or unique
            keys, and for any transactions that update parent tables in
            a foreign key relationship.
          </p><p>
            To set <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code> as the value for
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>,
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            must be set to specify an algorithm (not set to
            <code class="literal">OFF</code>). The default in MySQL 8.0 is that
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            is set to <code class="literal">XXHASH64</code>. The value that you
            select for
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            cannot be changed again while the value of
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            remains as <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code>.
          </p><p>
            The number of row hashes to be kept and checked for the
            latest transaction to have changed a given row is determined
            by the value of
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_history_size"><code class="literal">binlog_transaction_dependency_history_size</code></a>.
          </p><p>
            For Group Replication, setting
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking=WRITESET_SESSION</code></a>
            can improve performance for a group member, depending on the
            group's workload. Group Replication carries out its own
            parallelization after certification when applying
            transactions from the relay log, independently of the value
            set for
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>.
            However, the value of
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            does affect how transactions are written to the binary logs
            on Group Replication members. The dependency information in
            those logs is used to assist the process of state transfer
            from a donor's binary log for distributed recovery, which
            takes place whenever a member joins or rejoins the group.
          </p></li><li class="listitem"><p><a name="sysvar_binlog_transaction_dependency_history_size"></a>
            <a class="indexterm" name="idm46444265453184"></a>

            <a class="indexterm" name="idm46444265452064"></a>

            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_history_size"><code class="literal">binlog_transaction_dependency_history_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_transaction_dependency_history_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-transaction-dependency-history-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_transaction_dependency_history_size">binlog_transaction_dependency_history_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">25000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1000000</code></td>
</tr></tbody></table>
</div>
<p>
            Sets an upper limit on the number of row hashes which are
            kept in memory and used for looking up the transaction that
            last modified a given row. Once this number of hashes has
            been reached, the history is purged.
          </p></li><li class="listitem"><p><a name="sysvar_expire_logs_days"></a>
            <a class="indexterm" name="idm46444265413648"></a>

            <a class="indexterm" name="idm46444265412592"></a>

            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for expire_logs_days"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--expire-logs-days=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_expire_logs_days">expire_logs_days</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">99</code></td>
</tr></tbody></table>
</div>
<p>
            Specifies the number of days before automatic removal of
            binary log files.
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> is
            deprecated, and will be removed in a future release.
            Instead, use
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>,
            which sets the binary log expiration period in seconds. If
            you do not set a value for either system variable, the
            default expiration period is 30 days. Possible removals
            happen at startup and when the binary log is flushed. Log
            flushing occurs as indicated in
            <a class="xref" href="server-administration.html#server-logs" title="5.4 MySQL Server Logs">Section 5.4, “MySQL Server Logs”</a>.
          </p><p>
            Any non-zero value that you specify for
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> is ignored
            if
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is also specified, and the value of
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is used instead as the binary log expiration period. A
            warning message is issued in this situation. A non-zero
            value for <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a>
            is only applied as the binary log expiration period if
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is not specified or is specified as 0.
          </p><p>
            To disable automatic purging of the binary log, specify a
            value of 0 explicitly for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>,
            and do not specify a value for
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a>. For
            compatibility with earlier releases, automatic purging is
            also disabled if you specify a value of 0 explicitly for
            <a class="link" href="replication.html#sysvar_expire_logs_days"><code class="literal">expire_logs_days</code></a> and do not
            specify a value for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>.
            In that case, the default for
            <a class="link" href="replication.html#sysvar_binlog_expire_logs_seconds"><code class="literal">binlog_expire_logs_seconds</code></a>
            is not applied.
          </p><p>
            To remove binary log files manually, use the
            <a class="link" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement"><code class="literal">PURGE BINARY LOGS</code></a> statement.
            See <a class="xref" href="sql-statements.html#purge-binary-logs" title="13.4.1.1 PURGE BINARY LOGS Statement">Section 13.4.1.1, “PURGE BINARY LOGS Statement”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_log_bin"></a>
            <a class="indexterm" name="idm46444265351760"></a>

            <a class="indexterm" name="idm46444265350720"></a>

            <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_bin"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin">log_bin</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr></tbody></table>
</div>
<p>
            Shows the status of binary logging on the server, either
            enabled (<code class="literal">ON</code>) or disabled
            (<code class="literal">OFF</code>). With binary logging enabled, the
            server logs all statements that change data to the binary
            log, which is used for backup and replication.
            <code class="literal">ON</code> means that the binary log is
            available, <code class="literal">OFF</code> means that it is not in
            use. The <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> option can
            be used to specify a base name and location for the binary
            log.
          </p><p>
            In earlier MySQL versions, binary logging was disabled by
            default, and was enabled if you specified the
            <code class="option">--log-bin</code> option. From MySQL 8.0, binary
            logging is enabled by default, with the
            <code class="literal">log_bin</code> system variable set to
            <code class="literal">ON</code>, whether or not you specify the
            <code class="option">--log-bin</code> option. The exception is if you
            use <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> to initialize the data
            directory manually by invoking it with the
            <code class="option">--initialize</code> or
            <code class="option">--initialize-insecure</code> option, when binary
            logging is disabled by default. It is possible to enable
            binary logging in this case by specifying the
            <code class="option">--log-bin</code> option.


          </p><p>
            If the
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            or
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--disable-log-bin</code></a>
            option is specified at startup, binary logging is disabled,
            with the <code class="literal">log_bin</code> system variable set to
            <code class="literal">OFF</code>. If either of these options is
            specified and <code class="option">--log-bin</code> is also specified,
            the option specified later takes precedence.
          </p><p>
            For information on the format and management of the binary
            log, see <a class="xref" href="server-administration.html#binary-log" title="5.4.4 The Binary Log">Section 5.4.4, “The Binary Log”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_log_bin_basename"></a>
            <a class="indexterm" name="idm46444265309584"></a>

            <a class="indexterm" name="idm46444265308528"></a>

            <a class="link" href="replication.html#sysvar_log_bin_basename"><code class="literal">log_bin_basename</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_bin_basename"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin_basename">log_bin_basename</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr></tbody></table>
</div>
<p>
            Holds the base name and path for the binary log files, which
            can be set with the <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a>
            server option. In MySQL 8.0, if the
            <code class="option">--log-bin</code> option is not supplied, the
            default base name is <code class="filename">binlog</code>. For
            compatibility with MySQL 5.7, if the
            <code class="option">--log-bin</code> option is supplied with no string
            or with an empty string, the default base name is
            <code class="filename"><em class="replaceable"><code>host_name</code></em>-bin</code>,
            using the name of the host machine. The default location is
            the data directory.

            
          </p></li><li class="listitem"><p><a name="sysvar_log_bin_index"></a>
            <a class="indexterm" name="idm46444265278368"></a>

            <a class="indexterm" name="idm46444265277312"></a>

            <a class="link" href="replication.html#sysvar_log_bin_index"><code class="literal">log_bin_index</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log-bin-index"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-bin-index=file_name</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin_index">log_bin_index</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>File name</td>
</tr></tbody></table>
</div>
<p>
            Holds the base name and path for the binary log index file,
            which can be set with the
            <a class="link" href="replication.html#option_mysqld_log-bin-index"><code class="option">--log-bin-index</code></a> server
            option.
          </p></li><li class="listitem"><p><a name="sysvar_log_bin_trust_function_creators"></a>
            <a class="indexterm" name="idm46444265247424"></a>

            <a class="indexterm" name="idm46444265246320"></a>

            <a class="link" href="replication.html#sysvar_log_bin_trust_function_creators"><code class="literal">log_bin_trust_function_creators</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_bin_trust_function_creators"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-bin-trust-function-creators[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin_trust_function_creators">log_bin_trust_function_creators</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            This variable applies when binary logging is enabled. It
            controls whether stored function creators can be trusted not
            to create stored functions that will cause unsafe events to
            be written to the binary log. If set to 0 (the default),
            users are not permitted to create or alter stored functions
            unless they have the <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a>
            privilege in addition to the <a class="link" href="security.html#priv_create-routine"><code class="literal">CREATE
            ROUTINE</code></a> or <a class="link" href="security.html#priv_alter-routine"><code class="literal">ALTER
            ROUTINE</code></a> privilege. A setting of 0 also enforces
            the restriction that a function must be declared with the
            <code class="literal">DETERMINISTIC</code> characteristic, or with the
            <code class="literal">READS SQL DATA</code> or <code class="literal">NO
            SQL</code> characteristic. If the variable is set to 1,
            MySQL does not enforce these restrictions on stored function
            creation. This variable also applies to trigger creation.
            See <a class="xref" href="stored-objects.html#stored-programs-logging" title="24.7 Stored Program Binary Logging">Section 24.7, “Stored Program Binary Logging”</a>.
          </p></li><li class="listitem"><p><a name="sysvar_log_bin_use_v1_row_events"></a>
            <a class="indexterm" name="idm46444265207104"></a>

            <a class="indexterm" name="idm46444265206000"></a>

            <a class="link" href="replication.html#sysvar_log_bin_use_v1_row_events"><code class="literal">log_bin_use_v1_row_events</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_bin_use_v1_row_events"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-bin-use-v1-row-events[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Deprecated</strong></span></td>
<td>8.0.18</td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_bin_use_v1_row_events">log_bin_use_v1_row_events</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            This read-only system variable is deprecated. Setting the
            system variable to <code class="literal">ON</code> at server startup
            enabled row-based replication with slaves running MySQL
            Server 5.5 and earlier by writing the binary log using
            Version 1 binary log row events, instead of Version 2 binary
            log row events which are the default as of MySQL 5.6.
          </p></li><li class="listitem"><p><a name="sysvar_log_slave_updates"></a>
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a>

            <a class="indexterm" name="idm46444265169120"></a>

            <a class="indexterm" name="idm46444265168080"></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_slave_updates"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-slave-updates[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_slave_updates">log_slave_updates</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            Whether updates received by a slave server from a master
            server should be logged to the slave's own binary log.
          </p><p>
            Enabling this variable causes the slave to write the updates
            that are received from a master server and performed by the
            slave's SQL thread to the slave's own binary log. Binary
            logging, which is controlled by the
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> option and is
            enabled by default, must also be enabled on the slave for
            updates to be logged. See
            <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> is
            enabled by default, unless you specify
            <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
            to disable binary logging, in which case MySQL also disables
            slave update logging by default. If you need to disable
            slave update logging when binary logging is enabled, specify
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> at
            slave server startup.
          </p><p>
            Enabling <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a>
            enables replication servers to be chained. For example, you
            might want to set up replication servers using this
            arrangement:
          </p><pre data-lang="none" class="programlisting">A -&gt; B -&gt; C</pre><p>
            Here, <code class="literal">A</code> serves as the master for the
            slave <code class="literal">B</code>, and <code class="literal">B</code> serves
            as the master for the slave <code class="literal">C</code>. For this
            to work, <code class="literal">B</code> must be both a master
            <span class="emphasis"><em>and</em></span> a slave. With binary logging
            enabled and
            <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> enabled,
            which are the default settings, updates received from
            <code class="literal">A</code> are logged by <code class="literal">B</code> to
            its binary log, and can therefore be passed on to
            <code class="literal">C</code>.
          </p></li><li class="listitem"><p><a name="sysvar_log_statements_unsafe_for_binlog"></a>
            <a class="indexterm" name="idm46444265120688"></a>

            <a class="indexterm" name="idm46444265119584"></a>

            <a class="link" href="replication.html#sysvar_log_statements_unsafe_for_binlog"><code class="literal">log_statements_unsafe_for_binlog</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for log_statements_unsafe_for_binlog"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--log-statements-unsafe-for-binlog[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_log_statements_unsafe_for_binlog">log_statements_unsafe_for_binlog</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            If error 1592 is encountered, controls whether the generated
            warnings are added to the error log or not.
          </p></li><li class="listitem"><p><a name="sysvar_master_verify_checksum"></a>
            <a class="link" href="replication.html#sysvar_master_verify_checksum"><code class="literal">master_verify_checksum</code></a>
</p><a class="indexterm" name="idm46444265086176"></a><a class="indexterm" name="idm46444265085136"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for master_verify_checksum"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--master-verify-checksum[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_master_verify_checksum">master_verify_checksum</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr></tbody></table>
</div>
<p>
            Enabling this variable causes the master to verify events
            read from the binary log by examining checksums, and to stop
            with an error in the event of a mismatch.
            <a class="link" href="replication.html#sysvar_master_verify_checksum"><code class="literal">master_verify_checksum</code></a> is
            disabled by default; in this case, the master uses the event
            length from the binary log to verify events, so that only
            complete events are read from the binary log.
          </p></li><li class="listitem"><p><a name="sysvar_max_binlog_cache_size"></a>
            <a class="indexterm" name="idm46444265052960"></a>

            <a class="indexterm" name="idm46444265051920"></a>

            <a class="link" href="replication.html#sysvar_max_binlog_cache_size"><code class="literal">max_binlog_cache_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max_binlog_cache_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-binlog-cache-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_cache_size">max_binlog_cache_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">18446744073709551615</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">4096</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">18446744073709551615</code></td>
</tr></tbody></table>
</div>
<p>
            If a transaction requires more than this many bytes of
            memory, the server generates a <span class="errortext">Multi-statement
            transaction required more than 'max_binlog_cache_size' bytes
            of storage</span> error. The minimum value is 4096. The
            maximum possible value is 16EiB (exbibytes). The maximum
            recommended value is 4GB; this is due to the fact that MySQL
            currently cannot work with binary log positions greater than
            4GB.
          </p><p>
            <code class="literal">max_binlog_cache_size</code> sets the size for
            the transaction cache only; the upper limit for the
            statement cache is governed by the
            <a class="link" href="replication.html#sysvar_max_binlog_stmt_cache_size"><code class="literal">max_binlog_stmt_cache_size</code></a>
            system variable.
          </p><p>
            The visibility to sessions of
            <code class="literal">max_binlog_cache_size</code> matches that of the
            <a class="link" href="replication.html#sysvar_binlog_cache_size"><code class="literal">binlog_cache_size</code></a> system
            variable; in other words, changing its value affects only
            new sessions that are started after the value is changed.
          </p></li><li class="listitem"><p><a name="sysvar_max_binlog_size"></a>
            <a class="indexterm" name="idm46444265007776"></a>

            <a class="indexterm" name="idm46444265006768"></a>

            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max_binlog_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-binlog-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_size">max_binlog_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">4096</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">1073741824</code></td>
</tr></tbody></table>
</div>
<p>
            If a write to the binary log causes the current log file
            size to exceed the value of this variable, the server
            rotates the binary logs (closes the current file and opens
            the next one). The minimum value is 4096 bytes. The maximum
            and default value is 1GB. Encrypted binary log files have an
            additional 512-byte header, which is included in
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>.
          </p><p>
            A transaction is written in one chunk to the binary log, so
            it is never split between several binary logs. Therefore, if
            you have big transactions, you might see binary log files
            larger than
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>.
          </p><p>
            If <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> is 0,
            the value of
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a> applies to
            relay logs as well.
          </p><p>
            With GTIDs in use on the server, when
            <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a> is reached,
            if the system table <code class="literal">mysql.gtid_executed</code>
            cannot be accessed to write the GTIDs from the current
            binary log file, the binary log cannot be rotated. In this
            situation, the server responds according to its
            <a class="link" href="replication.html#sysvar_binlog_error_action"><code class="literal">binlog_error_action</code></a>
            setting. If <code class="literal">IGNORE_ERROR</code> is set, an error
            is logged on the server and binary logging is halted, or if
            <code class="literal">ABORT_SERVER</code> is set, the server shuts
            down.


          </p></li><li class="listitem"><p><a name="sysvar_max_binlog_stmt_cache_size"></a>
            <a class="indexterm" name="idm46444264956752"></a>

            <a class="indexterm" name="idm46444264955648"></a>

            <a class="link" href="replication.html#sysvar_max_binlog_stmt_cache_size"><code class="literal">max_binlog_stmt_cache_size</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for max_binlog_stmt_cache_size"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--max-binlog-stmt-cache-size=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_max_binlog_stmt_cache_size">max_binlog_stmt_cache_size</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">18446744073709547520</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">4096</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">18446744073709547520</code></td>
</tr></tbody></table>
</div>
<p>
            If nontransactional statements within a transaction require
            more than this many bytes of memory, the server generates an
            error. The minimum value is 4096. The maximum and default
            values are 4GB on 32-bit platforms and 16EB (exabytes) on
            64-bit platforms.
          </p><p>
            <code class="literal">max_binlog_stmt_cache_size</code> sets the size
            for the statement cache only; the upper limit for the
            transaction cache is governed exclusively by the
            <a class="link" href="replication.html#sysvar_max_binlog_cache_size"><code class="literal">max_binlog_cache_size</code></a>
            system variable.
          </p></li><li class="listitem"><p><a name="sysvar_original_commit_timestamp"></a>
            <a class="indexterm" name="idm46444264914672"></a>

            <a class="indexterm" name="idm46444264913568"></a>

            <a class="link" href="replication.html#sysvar_original_commit_timestamp"><code class="literal">original_commit_timestamp</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for original_commit_timestamp"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_original_commit_timestamp">original_commit_timestamp</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Numeric</td>
</tr></tbody></table>
</div>
<p>
            For internal use by replication. When re-executing a
            transaction on a slave, this is set to the time when the
            transaction was committed on the original master, measured
            in microseconds since the epoch. This allows the original
            commit timestamp to be propagated throughout a replication
            topology.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have either the
            <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege
            (see <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>), or
            privileges sufficient to set restricted session variables
            (see <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>). However,
            note that the variable is not intended for users to set; it
            is set automatically by the replication infrastructure.
          </p></li><li class="listitem"><p><a name="sysvar_sql_log_bin"></a>
            <a class="indexterm" name="idm46444264883984"></a>

            <a class="indexterm" name="idm46444264882976"></a>

            <a class="link" href="replication.html#sysvar_sql_log_bin"><code class="literal">sql_log_bin</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sql_log_bin"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sql_log_bin">sql_log_bin</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
            This variable controls whether logging to the binary log is
            enabled for the current session (assuming that the binary
            log itself is enabled). The default value is
            <code class="literal">ON</code>. To disable or enable binary logging
            for the current session, set the session
            <a class="link" href="replication.html#sysvar_sql_log_bin"><code class="literal">sql_log_bin</code></a> variable to
            <code class="literal">OFF</code> or <code class="literal">ON</code>.
          </p><p>
            Set this variable to <code class="literal">OFF</code> for a session to
            temporarily disable binary logging while making changes to
            the master you do not want replicated to the slave.
          </p><p>
            Setting the session value of this system variable is a
            restricted operation. The session user must have privileges
            sufficient to set restricted session variables. See
            <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          </p><p>
            It is not possible to set the session value of
            <a class="link" href="replication.html#sysvar_sql_log_bin"><code class="literal">sql_log_bin</code></a> within a
            transaction or subquery.
          </p><p>
            <span class="emphasis"><em>Setting this variable to <code class="literal">OFF</code>
            prevents GTIDs from being assigned to transactions in the
            binary log</em></span>. If you are using GTIDs for
            replication, this means that even when binary logging is
            later enabled again, the GTIDs written into the log from
            this point do not account for any transactions that occurred
            in the meantime, so in effect those transactions are lost.
          </p></li><li class="listitem"><p><a name="sysvar_sync_binlog"></a>
            <a class="indexterm" name="idm46444264844448"></a>

            <a class="indexterm" name="idm46444264843392"></a>

            <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for sync_binlog"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--sync-binlog=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_sync_binlog">sync_binlog</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
            Controls how often the MySQL server synchronizes the binary
            log to disk.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=0</code></a>: Disables
                synchronization of the binary log to disk by the MySQL
                server. Instead, the MySQL server relies on the
                operating system to flush the binary log to disk from
                time to time as it does for any other file. This setting
                provides the best performance, but in the event of a
                power failure or operating system crash, it is possible
                that the server has committed transactions that have not
                been synchronized to the binary log.
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a>: Enables
                synchronization of the binary log to disk before
                transactions are committed. This is the safest setting
                but can have a negative impact on performance due to the
                increased number of disk writes. In the event of a power
                failure or operating system crash, transactions that are
                missing from the binary log are only in a prepared
                state. This permits the automatic recovery routine to
                roll back the transactions, which guarantees that no
                transaction is lost from the binary log.
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=<em class="replaceable"><code>N</code></em></code></a>,
                where <em class="replaceable"><code>N</code></em> is a value other than
                0 or 1: The binary log is synchronized to disk after
                <code class="literal">N</code> binary log commit groups have been
                collected. In the event of a power failure or operating
                system crash, it is possible that the server has
                committed transactions that have not been flushed to the
                binary log. This setting can have a negative impact on
                performance due to the increased number of disk writes.
                A higher value improves performance, but with an
                increased risk of data loss.
</p></li></ul>
</div>
<p>
            For the greatest possible durability and consistency in a
            replication setup that uses <code class="literal">InnoDB</code> with
            transactions, use these settings:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a>.
              </p></li><li class="listitem"><p>
                <a class="link" href="innodb-storage-engine.html#sysvar_innodb_flush_log_at_trx_commit"><code class="literal">innodb_flush_log_at_trx_commit=1</code></a>.
</p></li></ul>
</div>
<div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Caution
</div>
<p>
              Many operating systems and some disk hardware fool the
              flush-to-disk operation. They may tell
              <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> that the flush has taken place,
              even though it has not. In this case, the durability of
              transactions is not guaranteed even with the recommended
              settings, and in the worst case, a power outage can
              corrupt <code class="literal">InnoDB</code> data. Using a
              battery-backed disk cache in the SCSI disk controller or
              in the disk itself speeds up file flushes, and makes the
              operation safer. You can also try to disable the caching
              of disk writes in hardware caches.
</p>
</div>
</li><li class="listitem"><p><a name="sysvar_transaction_write_set_extraction"></a>
            <a class="indexterm" name="idm46444264786704"></a>

            <a class="indexterm" name="idm46444264785664"></a>

            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for transaction_write_set_extraction"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--transaction-write-set-extraction[=value]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_transaction_write_set_extraction">transaction_write_set_extraction</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">XXHASH64</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">OFF</code></p><p class="valid-value"><code class="literal">MURMUR32</code></p><p class="valid-value"><code class="literal">XXHASH64</code></p></td>
</tr></tbody></table>
</div>
<p>
            For a replication master that has multithreaded slaves
            (replication slaves on which
            <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> is
            set to a value greater than 0), where
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            is set to <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code> to generate dependency
            information from the master's write set,
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            specifies the algorithm used to hash the writes extracted
            during a transaction.
          </p><p>
            When <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code> is set as the value for
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>,
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            must be set to specify an algorithm (not set to
            <code class="literal">OFF</code>). The default in MySQL 8.0 is that
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            is set to <code class="literal">XXHASH64</code>. While the current
            value of
            <a class="link" href="replication.html#sysvar_binlog_transaction_dependency_tracking"><code class="literal">binlog_transaction_dependency_tracking</code></a>
            is <code class="literal">WRITESET</code> or
            <code class="literal">WRITESET_SESSION</code>, you cannot change the
            value of
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>.
          </p><p>
            For Group Replication,
            <a class="link" href="replication.html#sysvar_transaction_write_set_extraction"><code class="literal">transaction_write_set_extraction</code></a>
            must be set to <code class="literal">XXHASH64</code>. The process of
            extracting the writes from a transaction is used in Group
            Replication for conflict detection and certification on all
            group members. See
            <a class="xref" href="group-replication.html#group-replication-requirements" title="18.9.1 Group Replication Requirements">Section 18.9.1, “Group Replication Requirements”</a>.
          </p><p>
            As of MySQL 8.0.14, setting the session value of this system
            variable is a restricted operation. The session user must
            have privileges sufficient to set restricted session
            variables. See <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-options-gtids"></a>17.1.6.5 Global Transaction ID System Variables</h4>

</div>

</div>

</div>
<p>
      The MySQL Server system variables described in this section are
      used to monitor and control Global Transaction Identifiers
      (GTIDs). For additional information, see
      <a class="xref" href="replication.html#replication-gtids" title="17.1.3 Replication with Global Transaction Identifiers">Section 17.1.3, “Replication with Global Transaction Identifiers”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="sysvar_binlog_gtid_simple_recovery"></a>
          <a class="indexterm" name="idm46444264720368"></a>

          <a class="indexterm" name="idm46444264719328"></a>

          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for binlog_gtid_simple_recovery"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--binlog-gtid-simple-recovery[={OFF|ON}]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery">binlog_gtid_simple_recovery</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Boolean</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">ON</code></td>
</tr></tbody></table>
</div>
<p>
          This variable controls how binary log files are iterated
          during the search for GTIDs when MySQL starts or restarts.
        </p><p>
          When
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=TRUE</code></a>,
          which is the default in MySQL 8.0, the values of
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> are computed at
          startup based on the values of
          <code class="literal">Previous_gtids_log_event</code> in the most recent
          and oldest binary log files. For a description of the
          computation, see
          <a class="xref" href="replication.html#replication-gtids-gtid-purged" title="The gtid_purged System Variable">The <code class="literal">gtid_purged</code> System Variable</a>. This setting
          accesses only two binary log files during server restart. If
          all binary logs on the server were generated using MySQL 5.7.8
          or later,
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=TRUE</code></a>
          can always safely be used.


        </p><p>
          If any binary logs from MySQL 5.7.7 or older are present on
          the server (for example, following an upgrade of an older
          server to MySQL 8.0), with
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=TRUE</code></a>,
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> might be
          initialized incorrectly in the following two situations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              The newest binary log was generated by MySQL 5.7.5 or
              earlier, and <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
              was <code class="literal">ON</code> for some binary logs but
              <code class="literal">OFF</code> for the newest binary log.
            </p></li><li class="listitem"><p>
              A <code class="literal">SET @@GLOBAL.gtid_purged</code> statement
              was issued on MySQL 5.7.7 or earlier, and the binary log
              that was active at the time of the <code class="literal">SET
              @@GLOBAL.gtid_purged</code> statement has not yet been
              purged.


</p></li></ul>
</div>
<p>
          If an incorrect GTID set is computed in either situation, it
          will remain incorrect even if the server is later restarted
          with
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>.
          If either of these situations apply or might apply on the
          server, set
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>
          before starting or restarting the server.
        </p><p>
          When
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>
          is set, the method of computing
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> as described in
          <a class="xref" href="replication.html#replication-gtids-gtid-purged" title="The gtid_purged System Variable">The <code class="literal">gtid_purged</code> System Variable</a> is changed to
          iterate the binary log files as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              Instead of using the value of
              <code class="literal">Previous_gtids_log_event</code> and GTID log
              events from the newest binary log file, the computation
              for <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
              iterates from the newest binary log file, and uses the
              value of <code class="literal">Previous_gtids_log_event</code> and
              any GTID log events from the first binary log file where
              it finds a <code class="literal">Previous_gtids_log_event</code>
              value. If the server's most recent binary log files do not
              have GTID log events, for example if
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> was used but
              the server was later changed to
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=OFF</code></a>, this
              process can take a long time.
            </p></li><li class="listitem"><p>
              Instead of using the value of
              <code class="literal">Previous_gtids_log_event</code> from the
              oldest binary log file, the computation for
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> iterates from
              the oldest binary log file, and uses the value of
              <code class="literal">Previous_gtids_log_event</code> from the first
              binary log file where it finds either a nonempty
              <code class="literal">Previous_gtids_log_event</code> value, or at
              least one GTID log event (indicating that the use of GTIDs
              starts at that point). If the server's older binary log
              files do not have GTID log events, for example if
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a> was only set
              recently on the server, this process can take a long time.
</p></li></ul>
</div>
</li><li class="listitem"><p><a name="sysvar_enforce_gtid_consistency"></a>
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a>
</p><a class="indexterm" name="idm46444264645792"></a><a class="indexterm" name="idm46444264644688"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for enforce_gtid_consistency"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--enforce-gtid-consistency[=value]</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_enforce_gtid_consistency">enforce_gtid_consistency</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">OFF</code></p><p class="valid-value"><code class="literal">ON</code></p><p class="valid-value"><code class="literal">WARN</code></p></td>
</tr></tbody></table>
</div>
<p>
          Depending on the value of this variable, the server enforces
          GTID consistency by allowing execution of only statements that
          can be safely logged using a GTID. You
          <span class="emphasis"><em>must</em></span> set this variable to
          <code class="literal">ON</code> before enabling GTID based replication.
        </p><p>
          The values that
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a> can
          be configured to are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">OFF</code>: all transactions are allowed to
              violate GTID consistency.
            </p></li><li class="listitem"><p>
              <code class="literal">ON</code>: no transaction is allowed to
              violate GTID consistency.
            </p></li><li class="listitem"><p>
              <code class="literal">WARN</code>: all transactions are allowed to
              violate GTID consistency, but a warning is generated in
              this case.
</p></li></ul>
</div>
<p>
          Only statements that can be logged using GTID safe statements
          can be logged when
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a> is
          set to <code class="literal">ON</code>, so the operations listed here
          cannot be used with this option:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
              TABLE ... SELECT</code></a> statements
            </p></li><li class="listitem"><p>
              <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
              TEMPORARY TABLE</code></a> or
              <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TEMPORARY
              TABLE</code></a> statements inside transactions
            </p></li><li class="listitem"><p>
              Transactions or statements that update both transactional
              and nontransactional tables. There is an exception that
              nontransactional DML is allowed in the same transaction or
              in the same statement as transactional DML, if all
              <span class="emphasis"><em>nontransactional</em></span> tables are
              temporary.
</p></li></ul>
</div>
<p>
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="option">--enforce-gtid-consistency</code></a> only
          takes effect if binary logging takes place for a statement. If
          binary logging is disabled on the server, or if statements are
          not written to the binary log because they are removed by a
          filter, GTID consistency is not checked or enforced for the
          statements that are not logged.
        </p><p>
          For more information, see
          <a class="xref" href="replication.html#replication-gtids-restrictions" title="17.1.3.6 Restrictions on Replication with GTIDs">Section 17.1.3.6, “Restrictions on Replication with GTIDs”</a>.
        </p><p>
          Prior to MySQL 5.7 and in early releases in that release
          series, the boolean
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a>
          defaulted to <code class="literal">OFF</code>. To maintain compatibility
          with these earlier releases, the enumeration defaults to
          <code class="literal">OFF</code>, and setting
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="option">--enforce-gtid-consistency</code></a>
          without a value is interpreted as setting the value to
          <code class="literal">ON</code>. The variable also has multiple textual
          aliases for the values: <code class="literal">0=OFF=FALSE</code>,
          <code class="literal">1=ON=TRUE</code>,<code class="literal">2=WARN</code>. This
          differs from other enumeration types but maintains
          compatibility with the boolean type used in previous releases.
          These changes impact on what is returned by the variable.
          Using <code class="literal">SELECT @@ENFORCE_GTID_CONSISTENCY</code>,
          <code class="literal">SHOW VARIABLES LIKE
          'ENFORCE_GTID_CONSISTENCY'</code>, and <code class="literal">SELECT *
          FROM INFORMATION_SCHEMA.VARIABLES WHERE 'VARIABLE_NAME' =
          'ENFORCE_GTID_CONSISTENCY'</code>, all return the textual
          form, not the numeric form. This is an incompatible change,
          since <code class="literal">@@ENFORCE_GTID_CONSISTENCY</code> returns
          the numeric form for booleans but returns the textual form for
          <code class="literal">SHOW</code> and the Information Schema.
        </p></li><li class="listitem"><p><a name="sysvar_gtid_executed"></a>
          <a class="indexterm" name="idm46444264576576"></a>

          <a class="indexterm" name="idm46444264575520"></a>

          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_executed"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_executed">gtid_executed</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_executed">gtid_executed</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
          When used with global scope, this variable contains a
          representation of the set of all transactions executed on the
          server and GTIDs that have been set by a
          <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> statement. This
          is the same as the value of the
          <code class="literal">Executed_Gtid_Set</code> column in the output of
          <a class="link" href="sql-statements.html#show-master-status" title="13.7.7.23 SHOW MASTER STATUS Statement"><code class="literal">SHOW MASTER STATUS</code></a> and
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>. The value of
          this variable is a GTID set, see
          <a class="xref" href="replication.html#replication-gtids-concepts-gtid-sets" title="GTID Sets">GTID Sets</a> for
          more information.
        </p><p>
          When the server starts,
          <code class="literal">@@GLOBAL.gtid_executed</code> is initialized. See
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery</code></a>
          for more information on how binary logs are iterated to
          populate <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. GTIDs
          are then added to the set as transactions are executed, or if
          any
          <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET</code></a>
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> statement is
          executed.
        </p><p>
          The set of transactions that can be found in the binary logs
          at any given time is equal to
          <a class="link" href="functions.html#function_gtid-subtract"><code class="literal">GTID_SUBTRACT(@@GLOBAL.gtid_executed,
          @@GLOBAL.gtid_purged)</code></a>; that is, to all transactions
          in the binary log that have not yet been purged.
        </p><p>
          Issuing <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> causes the
          global value (but not the session value) of this variable to
          be reset to an empty string. GTIDs are not otherwise removed
          from this set other than when the set is cleared due to
          <code class="literal">RESET MASTER</code>.
        </p><p>
          In some older releases, this variable could also be used with
          session scope, where it contained a representation of the set
          of transactions that are written to the cache in the current
          session. The session scope is now deprecated.
        </p></li><li class="listitem"><p><a name="sysvar_gtid_executed_compression_period"></a>
          <a class="link" href="replication.html#sysvar_gtid_executed_compression_period"><code class="literal">gtid_executed_compression_period</code></a>
</p><a class="indexterm" name="idm46444264517072"></a><a class="indexterm" name="idm46444264515984"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_executed_compression_period"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--gtid-executed-compression-period=#</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_executed_compression_period">gtid_executed_compression_period</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Integer</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">1000</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Minimum Value</strong></span></td>
<td><code class="literal">0</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Maximum Value</strong></span></td>
<td><code class="literal">4294967295</code></td>
</tr></tbody></table>
</div>
<p>
          Compress the <code class="literal">mysql.gtid_executed</code> table each
          time this many transactions have been processed. A setting of
          0 means that this table is not compressed. Since no
          compression of the table occurs when using the binary log,
          setting the value of the variable has no effect unless binary
          logging is disabled.
        </p><p>
          See
          <a class="xref" href="replication.html#replication-gtids-gtid-executed-table-compression" title="mysql.gtid_executed Table Compression">mysql.gtid_executed Table Compression</a>,
          for more information.
        </p></li><li class="listitem"><p><a name="sysvar_gtid_mode"></a>
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>
</p><a class="indexterm" name="idm46444264475744"></a><a class="indexterm" name="idm46444264474656"></a>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_mode"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>Command-Line Format</strong></span></td>
<td><code class="literal">--gtid-mode=MODE</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_mode">gtid_mode</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">OFF</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">OFF</code></p><p class="valid-value"><code class="literal">OFF_PERMISSIVE</code></p><p class="valid-value"><code class="literal">ON_PERMISSIVE</code></p><p class="valid-value"><code class="literal">ON</code></p></td>
</tr></tbody></table>
</div>
<p>
          Controls whether GTID based logging is enabled and what type
          of transactions the logs can contain. You must have privileges
          sufficient to set global system variables. See
          <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
          <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a> must
          be true before you can set
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>. Before
          modifying this variable, see
          <a class="xref" href="replication.html#replication-mode-change-online" title="17.1.5 Changing Replication Modes on Online Servers">Section 17.1.5, “Changing Replication Modes on Online Servers”</a>.
        </p><p>
          Logged transactions can be either anonymous or use GTIDs.
          Anonymous transactions rely on binary log file and position to
          identify specific transactions. GTID transactions have a
          unique identifier that is used to refer to transactions. The
          different modes are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">OFF</code>: Both new and replicated
              transactions must be anonymous.
            </p></li><li class="listitem"><p>
              <code class="literal">OFF_PERMISSIVE</code>: New transactions are
              anonymous. Replicated transactions can be either anonymous
              or GTID transactions.
            </p></li><li class="listitem"><p>
              <code class="literal">ON_PERMISSIVE</code>: New transactions are
              GTID transactions. Replicated transactions can be either
              anonymous or GTID transactions.
            </p></li><li class="listitem"><p>
              <code class="literal">ON</code>: Both new and replicated
              transactions must be GTID transactions.
</p></li></ul>
</div>
<p>
          Changes from one value to another can only be one step at a
          time. For example, if
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is currently set to
          <code class="literal">OFF_PERMISSIVE</code>, it is possible to change to
          <code class="literal">OFF</code> or <code class="literal">ON_PERMISSIVE</code> but
          not to <code class="literal">ON</code>.
        </p><p>
          The values of <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> and
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> are persistent
          regardless of the value of
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>. Therefore even
          after changing the value of
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>, these variables
          contain the correct values.
        </p></li><li class="listitem"><p><a name="sysvar_gtid_next"></a>
          <a class="indexterm" name="idm46444264416208"></a>

          <a class="indexterm" name="idm46444264415152"></a>

          <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_next"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_next">gtid_next</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>Enumeration</td>
</tr><tr><td scope="row"><span class="bold"><strong>Default Value</strong></span></td>
<td><code class="literal">AUTOMATIC</code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Valid Values</strong></span></td>
<td><p class="valid-value"><code class="literal">AUTOMATIC</code></p><p class="valid-value"><code class="literal">ANONYMOUS</code></p><p class="valid-value"><code class="literal">UUID:NUMBER</code></p></td>
</tr></tbody></table>
</div>
<p>
          This variable is used to specify whether and how the next GTID
          is obtained.
        </p><p>
          Setting the session value of this system variable is a
          restricted operation. The session user must have either the
          <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege
          (see <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>), or
          privileges sufficient to set restricted session variables (see
          <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>).
        </p><p>
          <code class="literal">gtid_next</code> can take any of the following
          values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">AUTOMATIC</code>: Use the next
              automatically-generated global transaction ID.
            </p></li><li class="listitem"><p>
              <code class="literal">ANONYMOUS</code>: Transactions do not have
              global identifiers, and are identified by file and
              position only.
            </p></li><li class="listitem"><p>
              A global transaction ID in
              <em class="replaceable"><code>UUID</code></em>:<em class="replaceable"><code>NUMBER</code></em>
              format.
</p></li></ul>
</div>
<p>
          Exactly which of the above options are valid depends on the
          setting of <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a>, see
          <a class="xref" href="replication.html#replication-mode-change-online-concepts" title="17.1.5.1 Replication Mode Concepts">Section 17.1.5.1, “Replication Mode Concepts”</a> for
          more information. Setting this variable has no effect if
          <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode</code></a> is
          <code class="literal">OFF</code>.
        </p><p>
          After this variable has been set to
          <em class="replaceable"><code>UUID</code></em>:<em class="replaceable"><code>NUMBER</code></em>,
          and a transaction has been committed or rolled back, an
          explicit <code class="literal">SET GTID_NEXT</code> statement must again
          be issued before any other statement.
        </p><p>
          <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TABLE</code></a> or
          <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TEMPORARY
          TABLE</code></a> fails with an explicit error when used on a
          combination of nontemporary tables with temporary tables, or
          of temporary tables using transactional storage engines with
          temporary tables using nontransactional storage engines.
        </p></li><li class="listitem"><p><a name="sysvar_gtid_owned"></a>
          <a class="indexterm" name="idm46444264361376"></a>

          <a class="indexterm" name="idm46444264360320"></a>

          <a class="link" href="replication.html#sysvar_gtid_owned"><code class="literal">gtid_owned</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_owned"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_owned">gtid_owned</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global, Session</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
          This read-only variable is primarily for internal use. Its
          contents depend on its scope.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              When used with global scope,
              <a class="link" href="replication.html#sysvar_gtid_owned"><code class="literal">gtid_owned</code></a> holds a list
              of all the GTIDs that are currently in use on the server,
              with the IDs of the threads that own them. This variable
              is mainly useful for a multi-threaded replication slave to
              check whether a transaction is already being applied on
              another thread. An applier thread takes ownership of a
              transaction's GTID all the time it is processing the
              transaction, so <code class="literal">@@global.gtid_owned</code>
              shows the GTID and owner for the duration of processing.
              When a transaction has been committed (or rolled back),
              the applier thread releases ownership of the GTID.
            </p></li><li class="listitem"><p>
              When used with session scope,
              <a class="link" href="replication.html#sysvar_gtid_owned"><code class="literal">gtid_owned</code></a> holds a single
              GTID that is currently in use by and owned by this
              session. This variable is mainly useful for testing and
              debugging the use of GTIDs when the client has explicitly
              assigned a GTID for the transaction by setting
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>. In this case,
              <code class="literal">@@session.gtid_owned</code> displays the GTID
              all the time the client is processing the transaction,
              until the transaction has been committed (or rolled back).
              When the client has finished processing the transaction,
              the variable is cleared. If
              <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next=AUTOMATIC</code></a> is
              used for the session,
              <a class="link" href="replication.html#sysvar_gtid_owned"><code class="literal">gtid_owned</code></a> is only
              populated briefly during the execution of the commit
              statement for the transaction, so it cannot be observed
              from the session concerned, although it will be listed if
              <code class="literal">@@global.gtid_owned</code> is read at the
              right point. If you have a requirement to track the GTIDs
              that are handled by a client in a session, you can enable
              the session state tracker controlled by the
              <a class="link" href="server-administration.html#sysvar_session_track_gtids"><code class="literal">session_track_gtids</code></a>
              system variable.
</p></li></ul>
</div>
</li><li class="listitem"><p><a name="sysvar_gtid_purged"></a>
          <a class="indexterm" name="idm46444264321152"></a>

          <a class="indexterm" name="idm46444264320144"></a>

          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>
</p>
<div class="informaltable">
<table frame="box" rules="all" summary="Properties for gtid_purged"><col width="30%"><col width="70%"><thead><tr><th scope="col">Property</th>
<th scope="col">Value</th>
</tr></thead><tbody><tr><td scope="row"><span class="bold"><strong>System Variable</strong></span></td>
<td><code class="literal"><a class="link" href="replication.html#sysvar_gtid_purged">gtid_purged</a></code></td>
</tr><tr><td scope="row"><span class="bold"><strong>Scope</strong></span></td>
<td>Global</td>
</tr><tr><td scope="row"><span class="bold"><strong>Dynamic</strong></span></td>
<td>Yes</td>
</tr><tr><td scope="row"><span class="bold"><strong><a class="link" href="optimization.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax"><code class="literal">SET_VAR</code></a> Hint Applies</strong></span></td>
<td>No</td>
</tr><tr><td scope="row"><span class="bold"><strong>Type</strong></span></td>
<td>String</td>
</tr></tbody></table>
</div>
<p>
          The global value of the
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> system variable
          (<code class="literal">@@GLOBAL.gtid_purged</code>) is a GTID set
          consisting of the GTIDs of all the transactions that have been
          committed on the server, but do not exist in any binary log
          file on the server.
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> is a subset of
          <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. The following
          categories of GTIDs are in
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              GTIDs of replicated transactions that were committed with
              binary logging disabled on the slave.
            </p></li><li class="listitem"><p>
              GTIDs of transactions that were written to a binary log
              file that has now been purged.
            </p></li><li class="listitem"><p>
              GTIDs that were added explicitly to the set by the
              statement <code class="literal">SET @@GLOBAL.gtid_purged</code>.
</p></li></ul>
</div>
<p>
          When the server starts, the global value of
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> is initialized to
          a set of GTIDs. For information on how this GTID set is
          computed, see <a class="xref" href="replication.html#replication-gtids-gtid-purged" title="The gtid_purged System Variable">The <code class="literal">gtid_purged</code> System Variable</a>.
          If binary logs from MySQL 5.7.7 or older are present on the
          server, you might need to set
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>
          in the server's configuration file to produce the correct
          computation. See the description for
          <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery</code></a>
          for details of the situations in which this setting is needed.
        </p><p>
          Issuing <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> causes the
          value of <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> to be
          reset to an empty string.
        </p><p>
          You can set the value of
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> in order to
          record on the server that the transactions in a certain GTID
          set have been applied, although they do not exist in any
          binary log on the server. An example use case for this action
          is when you are restoring a backup of one or more databases on
          a server, but you do not have the relevant binary logs
          containing the transactions on the server.
        </p><p>
          From MySQL 8.0, there are two ways to set the value of
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>. You can either
          replace the value of
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> with your
          specified GTID set, or you can append your specified GTID set
          to the GTID set that is already held by
          <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>. If the server
          has no existing GTIDs, for example an empty server that you
          are provisioning with a backup of an existing database, both
          methods have the same result. If you are restoring a backup
          that overlaps the transactions that are already on the server,
          for example replacing a corrupted table with a partial dump
          from the master made using <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> (which
          includes the GTIDs of all the transactions on the server, even
          though the dump is partial), use the first method of replacing
          the value of <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>. If
          you are restoring a backup that is disjoint from the
          transactions that are already on the server, for example
          provisioning a multi-source replication slave using dumps from
          two different servers, use the second method of adding to the
          value of <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              To replace the value of
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> with your
              specified GTID set, use the following statement:
            </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.gtid_purged = 'gtid_set'</pre><p>
              <code class="literal">gtid_set</code> must be a superset of the
              current value of
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>, and must not
              intersect with
              <code class="literal">gtid_subtract(gtid_executed,gtid_purged)</code>.
              In other words, the new GTID set
              <span class="bold"><strong>must</strong></span> include any GTIDs
              that were already in
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>, and
              <span class="bold"><strong>must not</strong></span> include any
              GTIDs in <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>
              that have not yet been purged. <code class="literal">gtid_set</code>
              also cannot include any GTIDs that are in
              <code class="literal">@@global.gtid_owned</code>, that is, the GTIDs
              for transactions that are currently being processed on the
              server.
            </p><p>
              The result is that the global value of
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> is set equal
              to <code class="literal">gtid_set</code>, and the value of
              <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> becomes the
              union of <code class="literal">gtid_set</code> and the previous
              value of <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>.
            </p></li><li class="listitem"><p>
              To append your specified GTID set to
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>, use the
              following statement with a plus sign (+) before the GTID
              set:
            </p><pre data-lang="sql" class="programlisting">SET @@GLOBAL.gtid_purged = '+gtid_set'</pre><p>
              <code class="literal">gtid_set</code> <span class="bold"><strong>must
              not</strong></span> intersect with the current value of
              <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>. In other
              words, the new GTID set must not include any GTIDs in
              <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a>, including
              transactions that are already also in
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>.
              <code class="literal">gtid_set</code> also cannot include any GTIDs
              that are in <code class="literal">@@global.gtid_owned</code>, that
              is, the GTIDs for transactions that are currently being
              processed on the server.
            </p><p>
              The result is that <code class="literal">gtid_set</code> is added to
              both <a class="link" href="replication.html#sysvar_gtid_executed"><code class="literal">gtid_executed</code></a> and
              <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a>.
</p></li></ul>
</div>
</li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
        If any binary logs from MySQL 5.7.7 or older are present on the
        server (for example, following an upgrade of an older server to
        MySQL 8.0), after issuing a <code class="literal">SET
        @@GLOBAL.gtid_purged</code> statement, you might need to set
        <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery=FALSE</code></a>
        in the server's configuration file before restarting the server,
        otherwise <a class="link" href="replication.html#sysvar_gtid_purged"><code class="literal">gtid_purged</code></a> can be
        computed incorrectly. See the description for
        <a class="link" href="replication.html#sysvar_binlog_gtid_simple_recovery"><code class="literal">binlog_gtid_simple_recovery</code></a> for
        details of the situations in which this setting is needed.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-administration"></a>17.1.7 Common Replication Administration Tasks</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-administration-status">17.1.7.1 Checking Replication Status</a></span></dt><dt><span class="section"><a href="replication.html#replication-administration-pausing">17.1.7.2 Pausing Replication on the Slave</a></span></dt></dl>
</div>
<p>
      Once replication has been started it executes without requiring
      much regular administration. This section describes how to check
      the status of replication and how to pause a slave.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-administration-status"></a>17.1.7.1 Checking Replication Status</h4>
</div>
</div>
</div>
<p>
        The most common task when managing a replication process is to
        ensure that replication is taking place and that there have been
        no errors between the slave and the master.
      </p><p>
        The <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> statement,
        which you must execute on each slave, provides information about
        the configuration and status of the connection between the slave
        server and the master server. From MySQL 5.7, the Performance
        Schema has replication tables that provide this information in a
        more accessible form. See
        <a class="xref" href="performance-schema.html#performance-schema-replication-tables" title="26.12.11 Performance Schema Replication Tables">Section 26.12.11, “Performance Schema Replication Tables”</a>.
      </p><p>
        The replication heartbeat information shown in the Performance
        Schema replication tables lets you check that the replication
        connection is active even if the master has not sent events to
        the slave recently. The master sends a heartbeat signal to a
        slave if there are no updates to, and no unsent events in, the
        binary log for a longer period than the heartbeat interval. The
        <code class="literal">MASTER_HEARTBEAT_PERIOD</code> setting on the master
        (set by the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
        statement) specifies the frequency of the heartbeat, which
        defaults to half of the connection timeout interval for the
        slave (<a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a>). The
        <a class="link" href="performance-schema.html#replication-connection-status-table" title="26.12.11.2 The replication_connection_status Table"><code class="literal">replication_connection_status</code></a>
        Performance Schema table shows when the most recent heartbeat
        signal was received by a replication slave, and how many
        heartbeat signals it has received.
      </p><p>
        If you are using the <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
        STATUS</code></a> statement to check on the status of an
        individual slave, the statement provides the following
        information:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW SLAVE STATUS\G</code></strong>
*************************** 1. row ***************************
               Slave_IO_State: Waiting for master to send event
                  Master_Host: master1
                  Master_User: root
                  Master_Port: 3306
                Connect_Retry: 60
              Master_Log_File: mysql-bin.000004
          Read_Master_Log_Pos: 931
               Relay_Log_File: slave1-relay-bin.000056
                Relay_Log_Pos: 950
        Relay_Master_Log_File: mysql-bin.000004
             Slave_IO_Running: Yes
            Slave_SQL_Running: Yes
              Replicate_Do_DB:
          Replicate_Ignore_DB:
           Replicate_Do_Table:
       Replicate_Ignore_Table:
      Replicate_Wild_Do_Table:
  Replicate_Wild_Ignore_Table:
                   Last_Errno: 0
                   Last_Error:
                 Skip_Counter: 0
          Exec_Master_Log_Pos: 931
              Relay_Log_Space: 1365
              Until_Condition: None
               Until_Log_File:
                Until_Log_Pos: 0
           Master_SSL_Allowed: No
           Master_SSL_CA_File:
           Master_SSL_CA_Path:
              Master_SSL_Cert:
            Master_SSL_Cipher:
               Master_SSL_Key:
        Seconds_Behind_Master: 0
Master_SSL_Verify_Server_Cert: No
                Last_IO_Errno: 0
                Last_IO_Error:
               Last_SQL_Errno: 0
               Last_SQL_Error:
  Replicate_Ignore_Server_Ids: 0
</pre><p>
        The key fields from the status report to examine are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">Slave_IO_State</code>: The current status of the
            slave. See <a class="xref" href="optimization.html#slave-io-thread-states" title="8.14.4 Replication Slave I/O Thread States">Section 8.14.4, “Replication Slave I/O Thread States”</a>, and
            <a class="xref" href="optimization.html#slave-sql-thread-states" title="8.14.5 Replication Slave SQL Thread States">Section 8.14.5, “Replication Slave SQL Thread States”</a>, for more
            information.
          </p></li><li class="listitem"><p>
            <code class="literal">Slave_IO_Running</code>: Whether the I/O thread
            for reading the master's binary log is running. Normally,
            you want this to be <code class="literal">Yes</code> unless you have
            not yet started replication or have explicitly stopped it
            with <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>.
          </p></li><li class="listitem"><p>
            <code class="literal">Slave_SQL_Running</code>: Whether the SQL thread
            for executing events in the relay log is running. As with
            the I/O thread, this should normally be
            <code class="literal">Yes</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">Last_IO_Error</code>,
            <code class="literal">Last_SQL_Error</code>: The last errors
            registered by the I/O and SQL threads when processing the
            relay log. Ideally these should be blank, indicating no
            errors.
          </p></li><li class="listitem"><p>
            <code class="literal">Seconds_Behind_Master</code>: The number of
            seconds that the slave SQL thread is behind processing the
            master binary log. A high number (or an increasing one) can
            indicate that the slave is unable to handle events from the
            master in a timely fashion.
          </p><p>
            A value of 0 for <code class="literal">Seconds_Behind_Master</code>
            can usually be interpreted as meaning that the slave has
            caught up with the master, but there are some cases where
            this is not strictly true. For example, this can occur if
            the network connection between master and slave is broken
            but the slave I/O thread has not yet noticed this—that
            is, <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a> has
            not yet elapsed.
          </p><p>
            It is also possible that transient values for
            <code class="literal">Seconds_Behind_Master</code> may not reflect the
            situation accurately. When the slave SQL thread has caught
            up on I/O, <code class="literal">Seconds_Behind_Master</code> displays
            0; but when the slave I/O thread is still queuing up a new
            event, <code class="literal">Seconds_Behind_Master</code> may show a
            large value until the SQL thread finishes executing the new
            event. This is especially likely when the events have old
            timestamps; in such cases, if you execute
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> several
            times in a relatively short period, you may see this value
            change back and forth repeatedly between 0 and a relatively
            large value.
</p></li></ul>
</div>
<p>
        Several pairs of fields provide information about the progress
        of the slave in reading events from the master binary log and
        processing them in the relay log:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            (<code class="literal">Master_Log_file</code>,
            <code class="literal">Read_Master_Log_Pos</code>): Coordinates in the
            master binary log indicating how far the slave I/O thread
            has read events from that log.
          </p></li><li class="listitem"><p>
            (<code class="literal">Relay_Master_Log_File</code>,
            <code class="literal">Exec_Master_Log_Pos</code>): Coordinates in the
            master binary log indicating how far the slave SQL thread
            has executed events received from that log.
          </p></li><li class="listitem"><p>
            (<code class="literal">Relay_Log_File</code>,
            <code class="literal">Relay_Log_Pos</code>): Coordinates in the slave
            relay log indicating how far the slave SQL thread has
            executed the relay log. These correspond to the preceding
            coordinates, but are expressed in slave relay log
            coordinates rather than master binary log coordinates.
</p></li></ul>
</div>
<p>
        On the master, you can check the status of connected slaves
        using <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW PROCESSLIST</code></a> to examine
        the list of running processes. Slave connections have
        <code class="literal">Binlog Dump</code> in the <code class="literal">Command</code>
        field:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW PROCESSLIST \G;</code></strong>
*************************** 4. row ***************************
     Id: 10
   User: root
   Host: slave1:58371
     db: NULL
Command: Binlog Dump
   Time: 777
  State: Has sent all binlog to slave; waiting for binlog to be updated
   Info: NULL
</pre><p>
        Because it is the slave that drives the replication process,
        very little information is available in this report.
      </p><p>
        For slaves that were started with the
        <a class="link" href="replication.html#sysvar_report_host"><code class="option">--report-host</code></a> option and are
        connected to the master, the <a class="link" href="sql-statements.html#show-slave-hosts" title="13.7.7.33 SHOW SLAVE HOSTS Statement"><code class="literal">SHOW SLAVE
        HOSTS</code></a> statement on the master shows basic information
        about the slaves. The output includes the ID of the slave
        server, the value of the
        <a class="link" href="replication.html#sysvar_report_host"><code class="option">--report-host</code></a> option, the
        connecting port, and master ID:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW SLAVE HOSTS;</code></strong>
+-----------+--------+------+-------------------+-----------+
| Server_id | Host   | Port | Rpl_recovery_rank | Master_id |
+-----------+--------+------+-------------------+-----------+
|        10 | slave1 | 3306 |                 0 |         1 |
+-----------+--------+------+-------------------+-----------+
1 row in set (0.00 sec)
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-administration-pausing"></a>17.1.7.2 Pausing Replication on the Slave</h4>

</div>

</div>

</div>
<p>
        You can stop and start replication on the slave using the
        <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> and
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statements.
      </p><p>
        To stop processing of the binary log from the master, use
        <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP SLAVE;</code></strong>
</pre><p>
        When replication is stopped, the slave I/O thread stops reading
        events from the master binary log and writing them to the relay
        log, and the SQL thread stops reading events from the relay log
        and executing them. You can pause the I/O or SQL thread
        individually by specifying the thread type:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP SLAVE IO_THREAD;</code></strong>
mysql&gt; <strong class="userinput"><code>STOP SLAVE SQL_THREAD;</code></strong>
</pre><p>
        To start execution again, use the <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
        SLAVE</code></a> statement:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre><p>
        To start a particular thread, specify the thread type:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE IO_THREAD;</code></strong>
mysql&gt; <strong class="userinput"><code>START SLAVE SQL_THREAD;</code></strong>
</pre><p>
        For a slave that performs updates only by processing events from
        the master, stopping only the SQL thread can be useful if you
        want to perform a backup or other task. The I/O thread will
        continue to read events from the master but they are not
        executed. This makes it easier for the slave to catch up when
        you restart the SQL thread.
      </p><p>
        Stopping only the I/O thread enables the events in the relay log
        to be executed by the SQL thread up to the point where the relay
        log ends. This can be useful when you want to pause execution to
        catch up with events already received from the master, when you
        want to perform administration on the slave but also ensure that
        it has processed all updates to a specific point. This method
        can also be used to pause event receipt on the slave while you
        conduct administration on the master. Stopping the I/O thread
        but permitting the SQL thread to run helps ensure that there is
        not a massive backlog of events to be executed when replication
        is started again.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="replication-implementation"></a>17.2 Replication Implementation</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-formats">17.2.1 Replication Formats</a></span></dt><dt><span class="section"><a href="replication.html#replication-implementation-details">17.2.2 Replication Implementation Details</a></span></dt><dt><span class="section"><a href="replication.html#replication-channels">17.2.3 Replication Channels</a></span></dt><dt><span class="section"><a href="replication.html#slave-logs">17.2.4 Replication Relay and Status Logs</a></span></dt><dt><span class="section"><a href="replication.html#replication-rules">17.2.5 How Servers Evaluate Replication Filtering Rules</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444264149584"></a><p>
    Replication is based on the master server keeping track of all
    changes to its databases (updates, deletes, and so on) in its binary
    log. The binary log serves as a written record of all events that
    modify database structure or content (data) from the moment the
    server was started. Typically, <a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT</code></a>
    statements are not recorded because they modify neither database
    structure nor content.
  </p><p>
    Each slave that connects to the master requests a copy of the binary
    log. That is, it pulls the data from the master, rather than the
    master pushing the data to the slave. The slave also executes the
    events from the binary log that it receives. This has the effect of
    repeating the original changes just as they were made on the master.
    Tables are created or their structure modified, and data is
    inserted, deleted, and updated according to the changes that were
    originally made on the master.
  </p><p>
    Because each slave is independent, the replaying of the changes from
    the master's binary log occurs independently on each slave that is
    connected to the master. In addition, because each slave receives a
    copy of the binary log only by requesting it from the master, the
    slave is able to read and update the copy of the database at its own
    pace and can start and stop the replication process at will without
    affecting the ability to update to the latest database status on
    either the master or slave side.
  </p><p>
    For more information on the specifics of the replication
    implementation, see
    <a class="xref" href="replication.html#replication-implementation-details" title="17.2.2 Replication Implementation Details">Section 17.2.2, “Replication Implementation Details”</a>.
  </p><p>
    Masters and slaves report their status in respect of the replication
    process regularly so that you can monitor them. See
    <a class="xref" href="optimization.html#thread-information" title="8.14 Examining Thread Information">Section 8.14, “Examining Thread Information”</a>, for descriptions of all
    replicated-related states.
  </p><p>
    The master binary log is written to a local relay log on the slave
    before it is processed. The slave also records information about the
    current position with the master's binary log and the local relay
    log. See <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>.
  </p><p>
    Database changes are filtered on the slave according to a set of
    rules that are applied according to the various configuration
    options and variables that control event evaluation. For details on
    how these rules are applied, see
    <a class="xref" href="replication.html#replication-rules" title="17.2.5 How Servers Evaluate Replication Filtering Rules">Section 17.2.5, “How Servers Evaluate Replication Filtering Rules”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-formats"></a>17.2.1 Replication Formats</h3>
</div>
</div>
</div>

<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-sbr-rbr">17.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based
Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-rbr-usage">17.2.1.2 Usage of Row-Based Logging and Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-rbr-safe-unsafe">17.2.1.3 Determination of Safe and Unsafe Statements in Binary Logging</a></span></dt></dl>
</div>
<p>
      Replication works because events written to the binary log are
      read from the master and then processed on the slave. The events
      are recorded within the binary log in different formats according
      to the type of event. The different replication formats used
      correspond to the binary logging format used when the events were
      recorded in the master's binary log. The correlation between
      binary logging formats and the terms used during replication are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When using statement-based binary logging, the master writes
          SQL statements to the binary log. Replication of the master to
          the slave works by executing the SQL statements on the slave.
          This is called <span class="firstterm">statement-based
          replication</span> (which can be abbreviated as
          <span class="firstterm">SBR</span>), which corresponds
          to the MySQL statement-based binary logging format.
        </p></li><li class="listitem"><p>
          When using row-based logging, the master writes
          <span class="firstterm">events</span> to the binary log
          that indicate how individual table rows are changed.
          Replication of the master to the slave works by copying the
          events representing the changes to the table rows to the
          slave. This is called <span class="firstterm">row-based
          replication</span> (which can be abbreviated as
          <span class="firstterm">RBR</span>).
        </p><p>
          Row-based logging is the default method.
        </p></li><li class="listitem"><p>
          You can also configure MySQL to use a mix of both
          statement-based and row-based logging, depending on which is
          most appropriate for the change to be logged. This is called
          <span class="firstterm">mixed-format logging</span>.
          When using mixed-format logging, a statement-based log is used
          by default. Depending on certain statements, and also the
          storage engine being used, the log is automatically switched
          to row-based in particular cases. Replication using the mixed
          format is referred to as
          <span class="firstterm">mixed-based replication</span>
          or <span class="firstterm">mixed-format
          replication</span>. For more information, see
          <a class="xref" href="server-administration.html#binary-log-mixed" title="5.4.4.3 Mixed Binary Logging Format">Section 5.4.4.3, “Mixed Binary Logging Format”</a>.
</p></li></ul>
</div>
<p><b>NDB Cluster. </b>
        The default binary logging format in MySQL NDB Cluster 8.0 is
        <code class="literal">MIXED</code>. You should note that NDB Cluster
        Replication always uses row-based replication, and that the
        <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a> storage engine is incompatible
        with statement-based replication. See
        <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-general" title="22.6.2 General Requirements for NDB Cluster Replication">Section 22.6.2, “General Requirements for NDB Cluster Replication”</a>, for more
        information.
      </p><p>
      When using <code class="literal">MIXED</code> format, the binary logging
      format is determined in part by the storage engine being used and
      the statement being executed. For more information on mixed-format
      logging and the rules governing the support of different logging
      formats, see <a class="xref" href="server-administration.html#binary-log-mixed" title="5.4.4.3 Mixed Binary Logging Format">Section 5.4.4.3, “Mixed Binary Logging Format”</a>.
    </p><p>
      The logging format in a running MySQL server is controlled by
      setting the <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> server
      system variable. This variable can be set with session or global
      scope. The rules governing when and how the new setting takes
      effect are the same as for other MySQL server system variables.
      Setting the variable for the current session lasts only until the
      end of that session, and the change is not visible to other
      sessions. Setting the variable globally takes effect for clients
      that connect after the change, but not for any current client
      sessions, including the session where the variable setting was
      changed. To make the global system variable setting permanent so
      that it applies across server restarts, you must set it in an
      option file. For more information, see
      <a class="xref" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment">Section 13.7.6.1, “SET Syntax for Variable Assignment”</a>.
    </p><p>
      There are conditions under which you cannot change the binary
      logging format at runtime or doing so causes replication to fail.
      See <a class="xref" href="server-administration.html#binary-log-setting" title="5.4.4.2 Setting The Binary Log Format">Section 5.4.4.2, “Setting The Binary Log Format”</a>.
    </p><p>
      Changing the global <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>
      value requires privileges sufficient to set global system
      variables. Changing the session
      <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> value requires
      privileges sufficient to set restricted session system variables.
      See <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>.
    </p><p>
      The statement-based and row-based replication formats have
      different issues and limitations. For a comparison of their
      relative advantages and disadvantages, see
      <a class="xref" href="replication.html#replication-sbr-rbr" title="17.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based Replication">Section 17.2.1.1, “Advantages and Disadvantages of Statement-Based and Row-Based
        Replication”</a>.
    </p><p>
      With statement-based replication, you may encounter issues with
      replicating stored routines or triggers. You can avoid these
      issues by using row-based replication instead. For more
      information, see <a class="xref" href="stored-objects.html#stored-programs-logging" title="24.7 Stored Program Binary Logging">Section 24.7, “Stored Program Binary Logging”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-sbr-rbr"></a>17.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based
Replication</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444264108272"></a><a class="indexterm" name="idm46444264106816"></a><p>
        Each binary logging format has advantages and disadvantages. For
        most users, the mixed replication format should provide the best
        combination of data integrity and performance. If, however, you
        want to take advantage of the features specific to the
        statement-based or row-based replication format when performing
        certain tasks, you can use the information in this section,
        which provides a summary of their relative advantages and
        disadvantages, to determine which is best for your needs.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="replication.html#replication-sbr-rbr-sbr-advantages" title="Advantages of statement-based replication">Advantages
            of statement-based replication</a>
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#replication-sbr-rbr-sbr-disadvantages" title="Disadvantages of statement-based replication">Disadvantages
            of statement-based replication</a>
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#replication-sbr-rbr-rbr-advantages" title="Advantages of row-based replication">Advantages
            of row-based replication</a>
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#replication-sbr-rbr-rbr-disadvantages" title="Disadvantages of row-based replication">Disadvantages
            of row-based replication</a>
</p></li></ul>
</div>
<h5><a name="replication-sbr-rbr-sbr-advantages"></a>Advantages of statement-based replication</h5>
<a class="indexterm" name="idm46444264095520"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Proven technology.
          </p></li><li class="listitem"><p>
            Less data written to log files. When updates or deletes
            affect many rows, this results in <span class="emphasis"><em>much</em></span>
            less storage space required for log files. This also means
            that taking and restoring from backups can be accomplished
            more quickly.
          </p></li><li class="listitem"><p>
            Log files contain all statements that made any changes, so
            they can be used to audit the database.
</p></li></ul>
</div>
<h5><a name="replication-sbr-rbr-sbr-disadvantages"></a>Disadvantages of statement-based replication</h5>
<a class="indexterm" name="idm46444264089168"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Statements that are unsafe for SBR. </b><a class="indexterm" name="idm46444264086512"></a><a class="indexterm" name="idm46444264084992"></a>
              Not all statements which modify data (such as
              <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>
              <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a>,
              <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>, and
              <a class="link" href="sql-statements.html#replace" title="13.2.9 REPLACE Statement"><code class="literal">REPLACE</code></a> statements) can be
              replicated using statement-based replication. Any
              nondeterministic behavior is difficult to replicate when
              using statement-based replication. Examples of such Data
              Modification Language (DML) statements include the
              following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                A statement that depends on a UDF or stored program that
                is nondeterministic, since the value returned by such a
                UDF or stored program or depends on factors other than
                the parameters supplied to it. (Row-based replication,
                however, simply replicates the value returned by the UDF
                or stored program, so its effect on table rows and data
                is the same on both the master and slave.) See
                <a class="xref" href="replication.html#replication-features-invoked" title="17.5.1.16 Replication of Invoked Features">Section 17.5.1.16, “Replication of Invoked Features”</a>, for more
                information.
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> and
                <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statements that
                use a <code class="literal">LIMIT</code> clause without an
                <code class="literal">ORDER BY</code> are nondeterministic. See
                <a class="xref" href="replication.html#replication-features-limit" title="17.5.1.18 Replication and LIMIT">Section 17.5.1.18, “Replication and LIMIT”</a>.
              </p></li><li class="listitem"><p>
                Locking read statements
                (<a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT ... FOR
                UPDATE</code></a> and
                <a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT ... FOR
                SHARE</code></a>) that use <code class="literal">NOWAIT</code> or
                <code class="literal">SKIP LOCKED</code> options. See
                <a class="xref" href="innodb-storage-engine.html#innodb-locking-reads-nowait-skip-locked" title="Locking Read Concurrency with NOWAIT and SKIP LOCKED">Locking Read Concurrency with NOWAIT and SKIP LOCKED</a>.
              </p></li><li class="listitem"><p>
                Deterministic UDFs must be applied on the slaves.
              </p></li><li class="listitem"><p>
                Statements using any of the following functions cannot
                be replicated properly using statement-based
                replication:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                    <a class="link" href="functions.html#function_load-file"><code class="literal">LOAD_FILE()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_uuid"><code class="literal">UUID()</code></a>,
                    <a class="link" href="functions.html#function_uuid-short"><code class="literal">UUID_SHORT()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_found-rows"><code class="literal">FOUND_ROWS()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_sysdate"><code class="literal">SYSDATE()</code></a> (unless
                    both the master and the slave are started with the
                    <a class="link" href="server-administration.html#option_mysqld_sysdate-is-now"><code class="option">--sysdate-is-now</code></a>
                    option)
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_is-free-lock"><code class="literal">IS_FREE_LOCK()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_is-used-lock"><code class="literal">IS_USED_LOCK()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_master-pos-wait"><code class="literal">MASTER_POS_WAIT()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_rand"><code class="literal">RAND()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_release-lock"><code class="literal">RELEASE_LOCK()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_sleep"><code class="literal">SLEEP()</code></a>
                  </p></li><li class="listitem"><p>
                    <a class="link" href="functions.html#function_version"><code class="literal">VERSION()</code></a>
</p></li></ul>
</div>
<p>
                However, all other functions are replicated correctly
                using statement-based replication, including
                <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a> and so forth.
              </p><p>
                For more information, see
                <a class="xref" href="replication.html#replication-features-functions" title="17.5.1.14 Replication and System Functions">Section 17.5.1.14, “Replication and System Functions”</a>.
</p></li></ul>
</div>
<p>
            Statements that cannot be replicated correctly using
            statement-based replication are logged with a warning like
            the one shown here:
          </p><pre data-lang="none" class="programlisting">[Warning] Statement is not safe to log in statement format.</pre><p>
            A similar warning is also issued to the client in such
            cases. The client can display it using
            <a class="link" href="sql-statements.html#show-warnings" title="13.7.7.40 SHOW WARNINGS Statement"><code class="literal">SHOW WARNINGS</code></a>.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT ...
            SELECT</code></a> requires a greater number of row-level
            locks than with row-based replication.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statements that
            require a table scan (because no index is used in the
            <code class="literal">WHERE</code> clause) must lock a greater number
            of rows than with row-based replication.
          </p></li><li class="listitem"><p>
            For <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>: An
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statement that uses
            <code class="literal">AUTO_INCREMENT</code> blocks other
            nonconflicting <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>
            statements.
          </p></li><li class="listitem"><p>
            For complex statements, the statement must be evaluated and
            executed on the slave before the rows are updated or
            inserted. With row-based replication, the slave only has to
            modify the affected rows, not execute the full statement.
          </p></li><li class="listitem"><p>
            If there is an error in evaluation on the slave,
            particularly when executing complex statements,
            statement-based replication may slowly increase the margin
            of error across the affected rows over time. See
            <a class="xref" href="replication.html#replication-features-slaveerrors" title="17.5.1.28 Slave Errors During Replication">Section 17.5.1.28, “Slave Errors During Replication”</a>.
          </p></li><li class="listitem"><p>
            Stored functions execute with the same
            <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a> value as the calling
            statement. However, this is not true of stored procedures.
          </p></li><li class="listitem"><p>
            Deterministic UDFs must be applied on the slaves.
          </p></li><li class="listitem"><p>
            Table definitions must be (nearly) identical on master and
            slave. See
            <a class="xref" href="replication.html#replication-features-differing-tables" title="17.5.1.9 Replication with Differing Table Definitions on Master and Slave">Section 17.5.1.9, “Replication with Differing Table Definitions on Master and Slave”</a>, for
            more information.
</p></li></ul>
</div>
<h5><a name="replication-sbr-rbr-rbr-advantages"></a>Advantages of row-based replication</h5>
<a class="indexterm" name="idm46444264006960"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            All changes can be replicated. This is the safest form of
            replication.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Statements that update the information in the
              <code class="literal">mysql</code> system schema—such as
              <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a>,
              <a class="link" href="sql-statements.html#revoke" title="13.7.1.8 REVOKE Statement"><code class="literal">REVOKE</code></a> and the manipulation
              of triggers, stored routines (including stored
              procedures), and views—are all replicated to slaves
              using statement-based replication.
            </p><p>
              For statements such as
              <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE
              ... SELECT</code></a>, a <code class="literal">CREATE</code>
              statement is generated from the table definition and
              replicated using statement-based format, while the row
              insertions are replicated using row-based format.
</p>
</div>
</li><li class="listitem"><p>
            Fewer row locks are required on the master, which thus
            achieves higher concurrency, for the following types of
            statements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="sql-statements.html#insert-select" title="13.2.6.1 INSERT ... SELECT Statement"><code class="literal">INSERT
                ... SELECT</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statements with
                <code class="literal">AUTO_INCREMENT</code>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> or
                <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statements with
                <code class="literal">WHERE</code> clauses that do not use keys or
                do not change most of the examined rows.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Fewer row locks are required on the slave for any
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>,
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>, or
            <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statement.
</p></li></ul>
</div>
<h5><a name="replication-sbr-rbr-rbr-disadvantages"></a>Disadvantages of row-based replication</h5>
<a class="indexterm" name="idm46444263981280"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            RBR can generate more data that must be logged. To replicate
            a DML statement (such as an
            <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> or
            <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statement),
            statement-based replication writes only the statement to the
            binary log. By contrast, row-based replication writes each
            changed row to the binary log. If the statement changes many
            rows, row-based replication may write significantly more
            data to the binary log; this is true even for statements
            that are rolled back. This also means that making and
            restoring a backup can require more time. In addition, the
            binary log is locked for a longer time to write the data,
            which may cause concurrency problems. Use
            <a class="link" href="replication.html#sysvar_binlog_row_image"><code class="literal">binlog_row_image=minimal</code></a> to
            reduce the disadvantage considerably.
          </p></li><li class="listitem"><p>
            Deterministic UDFs that generate large
            <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> values take longer to
            replicate with row-based replication than with
            statement-based replication. This is because the
            <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> column value is logged,
            rather than the statement generating the data.
          </p></li><li class="listitem"><p>
            You cannot see on the slave what statements were received
            from the master and executed. However, you can see what data
            was changed using <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> with the
            options
            <a class="link" href="programs.html#option_mysqlbinlog_base64-output"><code class="option">--base64-output=DECODE-ROWS</code></a>
            and <a class="link" href="programs.html#option_mysqlbinlog_verbose"><code class="option">--verbose</code></a>.
          </p><p>
            Alternatively, use the
            <a class="link" href="replication.html#sysvar_binlog_rows_query_log_events"><code class="literal">binlog_rows_query_log_events</code></a>
            variable, which if enabled adds a
            <code class="literal">Rows_query</code> event with the statement to
            <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output when the
            <code class="literal">-vv</code> option is used.
          </p></li><li class="listitem"><p>
            For tables using the <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a>
            storage engine, a stronger lock is required on the slave for
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statements when
            applying them as row-based events to the binary log than
            when applying them as statements. This means that concurrent
            inserts on <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a> tables are
            not supported when using row-based replication.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rbr-usage"></a>17.2.1.2 Usage of Row-Based Logging and Replication</h4>

</div>

</div>

</div>
<p>
        MySQL uses statement-based logging (SBL), row-based logging
        (RBL) or mixed-format logging. The type of binary log used
        impacts the size and efficiency of logging. Therefore the choice
        between row-based replication (RBR) or statement-based
        replication (SBR) depends on your application and environment.

        

        This section describes known issues when using a row-based
        format log, and describes some best practices using it in
        replication.
      </p><p>
        For additional information, see
        <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>, and
        <a class="xref" href="replication.html#replication-sbr-rbr" title="17.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based Replication">Section 17.2.1.1, “Advantages and Disadvantages of Statement-Based and Row-Based
        Replication”</a>.
      </p><p>
        For information about issues specific to NDB Cluster Replication
        (which depends on row-based replication), see
        <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-issues" title="22.6.3 Known Issues in NDB Cluster Replication">Section 22.6.3, “Known Issues in NDB Cluster Replication”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="replication-rbr-usage-temptables"></a><b>Row-based logging of temporary tables. </b>
              As noted in
              <a class="xref" href="replication.html#replication-features-temptables" title="17.5.1.30 Replication and Temporary Tables">Section 17.5.1.30, “Replication and Temporary Tables”</a>,
              temporary tables are not replicated when using row-based
              format or (from MySQL 8.0.4) mixed format. For more
              information, see <a class="xref" href="replication.html#replication-sbr-rbr" title="17.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based Replication">Section 17.2.1.1, “Advantages and Disadvantages of Statement-Based and Row-Based
        Replication”</a>.
            </p><p>
            Temporary tables are not replicated when using row-based or
            mixed format because there is no need. In addition, because
            temporary tables can be read only from the thread which
            created them, there is seldom if ever any benefit obtained
            from replicating them, even when using statement-based
            format.
          </p><p>
            You can switch from statement-based to row-based binary
            logging format at runtime even when temporary tables have
            been created. However, in MySQL 8.0, you cannot switch from
            row-based or mixed format for binary logging to
            statement-based format at runtime, because any
            <code class="literal">CREATE TEMPORARY TABLE</code> statements will
            have been omitted from the binary log in the previous mode.
          </p><p>
            The MySQL server tracks the logging mode that was in effect
            when each temporary table was created. When a given client
            session ends, the server logs a <code class="literal">DROP TEMPORARY
            TABLE IF EXISTS</code> statement for each temporary table
            that still exists and was created when statement-based
            binary logging was in use. If row-based or mixed format
            binary logging was in use when the table was created, the
            <code class="literal">DROP TEMPORARY TABLE IF EXISTS</code> statement
            is not logged. In releases before MySQL 8.0.4 and 5.7.25,
            the <code class="literal">DROP TEMPORARY TABLE IF EXISTS</code>
            statement was logged regardless of the logging mode that was
            in effect.
          </p><p>
            Nontransactional DML statements involving temporary tables
            are allowed when using
            <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>, as long
            as any nontransactional tables affected by the statements
            are temporary tables (Bug #14272672).
          </p></li><li class="listitem"><p><b>RBL and synchronization of nontransactional tables. </b>
              When many rows are affected, the set of changes is split
              into several events; when the statement commits, all of
              these events are written to the binary log. When executing
              on the slave, a table lock is taken on all tables
              involved, and then the rows are applied in batch mode.
              Depending on the engine used for the slave's copy of the
              table, this may or may not be effective.

              
            </p></li><li class="listitem"><p><b>Latency and binary log size. </b>
              RBL writes changes for each row to the binary log and so
              its size can increase quite rapidly. This can
              significantly increase the time required to make changes
              on the slave that match those on the master. You should be
              aware of the potential for this delay in your
              applications.
            </p></li><li class="listitem"><p><b>Reading the binary log. </b>
              <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> displays row-based events
              in the binary log using the <code class="literal">BINLOG</code>
              statement (see <a class="xref" href="sql-statements.html#binlog" title="13.7.8.1 BINLOG Statement">Section 13.7.8.1, “BINLOG Statement”</a>). This statement
              displays an event as a base 64-encoded string, the meaning
              of which is not evident. When invoked with the
              <a class="link" href="programs.html#option_mysqlbinlog_base64-output"><code class="option">--base64-output=DECODE-ROWS</code></a>
              and <a class="link" href="programs.html#option_mysqlbinlog_verbose"><code class="option">--verbose</code></a> options,
              <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> formats the contents of the
              binary log to be human readable. When binary log events
              were written in row-based format and you want to read or
              recover from a replication or database failure you can use
              this command to read contents of the binary log. For more
              information, see <a class="xref" href="programs.html#mysqlbinlog-row-events" title="4.6.8.2 mysqlbinlog Row Event Display">Section 4.6.8.2, “mysqlbinlog Row Event Display”</a>.
            </p></li><li class="listitem"><p><b>Binary log execution errors and slave_exec_mode. </b>
              Using
              <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode=IDEMPOTENT</code></a>
              is generally only useful with MySQL NDB Cluster
              replication, for which <code class="literal">IDEMPOTENT</code> is
              the default value. (See
              <a class="xref" href="mysql-cluster.html#mysql-cluster-replication-multi-master" title="22.6.10 NDB Cluster Replication: Multi-Master and Circular Replication">Section 22.6.10, “NDB Cluster Replication: Multi-Master and Circular Replication”</a>).
              When <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a> is
              <code class="literal">IDEMPOTENT</code>, a failure to apply changes
              from RBL because the original row cannot be found does not
              trigger an error or cause replication to fail. This means
              that it is possible that updates are not applied on the
              slave, so that the master and slave are no longer
              synchronized. Latency issues and use of nontransactional
              tables with RBR when
              <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a> is
              <code class="literal">IDEMPOTENT</code> can cause the master and
              slave to diverge even further. For more information about
              <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a>, see
              <a class="xref" href="server-administration.html#server-system-variables" title="5.1.8 Server System Variables">Section 5.1.8, “Server System Variables”</a>.
            </p><p>
            For other scenarios, setting
            <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a> to
            <code class="literal">STRICT</code> is normally sufficient; this is
            the default value for storage engines other than
            <a class="link" href="mysql-cluster.html" title="Chapter 22 MySQL NDB Cluster 8.0"><code class="literal">NDB</code></a>.
          </p></li><li class="listitem"><p><b>Filtering based on server ID not supported. </b>
              You can filter based on server ID by using the
              <code class="literal">IGNORE_SERVER_IDS</code> option for the
              <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement.
              This option works with statement-based and row-based
              logging formats, but is deprecated for use when
              <a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">GTID_MODE=ON</code></a> is set.
              Another method to filter out changes on some slaves is to
              use a <code class="literal">WHERE</code> clause that includes the
              relation <code class="literal">@@server_id &lt;&gt;
              <em class="replaceable"><code>id_value</code></em></code> clause with
              <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> and
              <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statements. For
              example, <code class="literal">WHERE @@server_id &lt;&gt; 1</code>.
              However, this does not work correctly with row-based
              logging. To use the
              <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a> system variable
              for statement filtering, use statement-based logging.
            </p></li><li class="listitem"><p><b>Database-level replication options. </b>
              The effects of the
              <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>,
              <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>, and
              <a class="link" href="replication.html#option_mysqld_replicate-rewrite-db"><code class="option">--replicate-rewrite-db</code></a>
              options differ considerably depending on whether row-based
              or statement-based logging is used. Therefore, it is
              recommended to avoid database-level options and instead
              use table-level options such as
              <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> and
              <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a>.
              For more information about these options and the impact
              replication format has on how they operate, see
              <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
            </p></li><li class="listitem"><p><b>RBL, nontransactional tables, and stopped slaves. </b>
              When using row-based logging, if the slave server is
              stopped while a slave thread is updating a
              nontransactional table, the slave database can reach an
              inconsistent state. For this reason, it is recommended
              that you use a transactional storage engine such as
              <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> for all tables
              replicated using the row-based format. Use of
              <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> or
              <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE
              SQL_THREAD</code></a> prior to shutting down the slave
              MySQL server helps prevent issues from occurring, and is
              always recommended regardless of the logging format or
              storage engine you use.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rbr-safe-unsafe"></a>17.2.1.3 Determination of Safe and Unsafe Statements in Binary Logging</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444263884992"></a><a class="indexterm" name="idm46444263883536"></a><a class="indexterm" name="idm46444263882032"></a><p>
        The <span class="quote">“<span class="quote">safeness</span>”</span> of a statement in MySQL replication
        refers to whether the statement and its effects can be
        replicated correctly using statement-based format. If this is
        true of the statement, we refer to the statement as
        <span class="firstterm">safe</span>; otherwise, we refer
        to it as <span class="firstterm">unsafe</span>.
      </p><p>
        In general, a statement is safe if it deterministic, and unsafe
        if it is not. However, certain nondeterministic functions are
        <span class="emphasis"><em>not</em></span> considered unsafe (see
        <a class="xref" href="replication.html#replication-rbr-safe-unsafe-not" title="Nondeterministic functions not considered unsafe">Nondeterministic functions not considered unsafe</a>, later in this
        section). In addition, statements using results from
        floating-point math functions—which are
        hardware-dependent—are always considered unsafe (see
        <a class="xref" href="replication.html#replication-features-floatvalues" title="17.5.1.12 Replication and Floating-Point Values">Section 17.5.1.12, “Replication and Floating-Point Values”</a>).
      </p><p><b>Handling of safe and unsafe statements. </b>
          A statement is treated differently depending on whether the
          statement is considered safe, and with respect to the binary
          logging format (that is, the current value of
          <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>).
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            When using row-based logging, no distinction is made in the
            treatment of safe and unsafe statements.
          </p></li><li class="listitem"><p>
            When using mixed-format logging, statements flagged as
            unsafe are logged using the row-based format; statements
            regarded as safe are logged using the statement-based
            format.
          </p></li><li class="listitem"><p>
            When using statement-based logging, statements flagged as
            being unsafe generate a warning to this effect. Safe
            statements are logged normally.
</p></li></ul>
</div>
<p>
        Each statement flagged as unsafe generates a warning. If a large
        number of such statements were executed on the master, this
        could lead to excessively large error log files. To prevent
        this, MySQL has a warning suppression mechanism. Whenever the 50
        most recent
        <a class="link" href="error-handling.html#error_er_binlog_unsafe_statement"><code class="literal">ER_BINLOG_UNSAFE_STATEMENT</code></a>
        warnings have been generated more than 50 times in any 50-second
        period, warning suppression is enabled. When activated, this
        causes such warnings not to be written to the error log;
        instead, for each 50 warnings of this type, a note <code class="literal">The
        last warning was repeated <em class="replaceable"><code>N</code></em> times in
        last <em class="replaceable"><code>S</code></em> seconds</code> is written
        to the error log. This continues as long as the 50 most recent
        such warnings were issued in 50 seconds or less; once the rate
        has decreased below this threshold, the warnings are once again
        logged normally. Warning suppression has no effect on how the
        safety of statements for statement-based logging is determined,
        nor on how warnings are sent to the client. MySQL clients still
        receive one warning for each such statement.
      </p><p>
        For more information, see <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
      </p><p><b>Statements considered unsafe. </b><a class="indexterm" name="idm46444263862640"></a>
          Statements with the following characteristics are considered
          unsafe:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Statements containing system functions that may return a different value
              on the slave. </b>
              These functions include
              <a class="link" href="functions.html#function_found-rows"><code class="literal">FOUND_ROWS()</code></a>,
              <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a>,
              <a class="link" href="functions.html#function_is-free-lock"><code class="literal">IS_FREE_LOCK()</code></a>,
              <a class="link" href="functions.html#function_is-used-lock"><code class="literal">IS_USED_LOCK()</code></a>,
              <a class="link" href="functions.html#function_load-file"><code class="literal">LOAD_FILE()</code></a>,
              <a class="link" href="functions.html#function_master-pos-wait"><code class="literal">MASTER_POS_WAIT()</code></a>,
              <a class="link" href="functions.html#function_rand"><code class="literal">RAND()</code></a>,
              <a class="link" href="functions.html#function_release-lock"><code class="literal">RELEASE_LOCK()</code></a>,
              <a class="link" href="functions.html#function_row-count"><code class="literal">ROW_COUNT()</code></a>,
              <a class="link" href="functions.html#function_session-user"><code class="literal">SESSION_USER()</code></a>,
              <a class="link" href="functions.html#function_sleep"><code class="literal">SLEEP()</code></a>,
              <a class="link" href="functions.html#function_sysdate"><code class="literal">SYSDATE()</code></a>,
              <a class="link" href="functions.html#function_system-user"><code class="literal">SYSTEM_USER()</code></a>,
              <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a>,
              <a class="link" href="functions.html#function_uuid"><code class="literal">UUID()</code></a>, and
              <a class="link" href="functions.html#function_uuid-short"><code class="literal">UUID_SHORT()</code></a>.
            </p><p><a name="replication-rbr-safe-unsafe-not"></a><b>Nondeterministic functions not considered unsafe. </b>
              Although these functions are not deterministic, they are
              treated as safe for purposes of logging and replication:
              <a class="link" href="functions.html#function_connection-id"><code class="literal">CONNECTION_ID()</code></a>,
              <a class="link" href="functions.html#function_curdate"><code class="literal">CURDATE()</code></a>,
              <a class="link" href="functions.html#function_current-date"><code class="literal">CURRENT_DATE()</code></a>,
              <a class="link" href="functions.html#function_current-time"><code class="literal">CURRENT_TIME()</code></a>,
              <a class="link" href="functions.html#function_current-timestamp"><code class="literal">CURRENT_TIMESTAMP()</code></a>,
              <a class="link" href="functions.html#function_curtime"><code class="literal">CURTIME()</code></a>,,
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>,
              <a class="link" href="functions.html#function_localtime"><code class="literal">LOCALTIME()</code></a>,
              <a class="link" href="functions.html#function_localtimestamp"><code class="literal">LOCALTIMESTAMP()</code></a>,
              <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a>,
              <a class="link" href="functions.html#function_unix-timestamp"><code class="literal">UNIX_TIMESTAMP()</code></a>,
              <a class="link" href="functions.html#function_utc-date"><code class="literal">UTC_DATE()</code></a>,
              <a class="link" href="functions.html#function_utc-time"><code class="literal">UTC_TIME()</code></a>, and
              <a class="link" href="functions.html#function_utc-timestamp"><code class="literal">UTC_TIMESTAMP()</code></a>.
            </p><p>
            For more information, see
            <a class="xref" href="replication.html#replication-features-functions" title="17.5.1.14 Replication and System Functions">Section 17.5.1.14, “Replication and System Functions”</a>.
          </p></li><li class="listitem"><p><b>References to system variables. </b>
              Most system variables are not replicated correctly using
              the statement-based format. See
              <a class="xref" href="replication.html#replication-features-variables" title="17.5.1.38 Replication and Variables">Section 17.5.1.38, “Replication and Variables”</a>. For
              exceptions, see <a class="xref" href="server-administration.html#binary-log-mixed" title="5.4.4.3 Mixed Binary Logging Format">Section 5.4.4.3, “Mixed Binary Logging Format”</a>.
            </p></li><li class="listitem"><p><b>UDFs. </b>
              Since we have no control over what a UDF does, we must
              assume that it is executing unsafe statements.
            </p></li><li class="listitem"><p><b>Fulltext plugin. </b>
              This plugin may behave differently on different MySQL
              servers; therefore, statements depending on it could have
              different results. For this reason, all statements relying
              on the fulltext plugin are treated as unsafe in MySQL.
            </p></li><li class="listitem"><p><b>Trigger or stored program updates a table having an AUTO_INCREMENT
              column. </b>
              This is unsafe because the order in which the rows are
              updated may differ on the master and the slave.
            </p><p>
            In addition, an <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> into a
            table that has a composite primary key containing an
            <code class="literal">AUTO_INCREMENT</code> column that is not the
            first column of this composite key is unsafe.
          </p><p>
            For more information, see
            <a class="xref" href="replication.html#replication-features-auto-increment" title="17.5.1.1 Replication and AUTO_INCREMENT">Section 17.5.1.1, “Replication and AUTO_INCREMENT”</a>.
          </p></li><li class="listitem"><p><b>INSERT ... ON DUPLICATE KEY UPDATE statements on tables with multiple
              primary or unique keys. </b>
              When executed against a table that contains more than one
              primary or unique key, this statement is considered
              unsafe, being sensitive to the order in which the storage
              engine checks the keys, which is not deterministic, and on
              which the choice of rows updated by the MySQL Server
              depends.
            </p><p>
            An
            <a class="link" href="sql-statements.html#insert-on-duplicate" title="13.2.6.2 INSERT ... ON DUPLICATE KEY UPDATE Statement"><code class="literal">INSERT
            ... ON DUPLICATE KEY UPDATE</code></a> statement against a
            table having more than one unique or primary key is marked
            as unsafe for statement-based replication. (Bug #11765650,
            Bug #58637)
          </p></li><li class="listitem"><p><b>Updates using LIMIT. </b>
              The order in which rows are retrieved is not specified,
              and is therefore considered unsafe. See
              <a class="xref" href="replication.html#replication-features-limit" title="17.5.1.18 Replication and LIMIT">Section 17.5.1.18, “Replication and LIMIT”</a>.
            </p></li><li class="listitem"><p><b>Accesses or references log tables. </b>
              The contents of the system log table may differ between
              master and slave.
            </p></li><li class="listitem"><p><b>Nontransactional operations after transactional operations. </b>
              Within a transaction, allowing any nontransactional reads
              or writes to execute after any transactional reads or
              writes is considered unsafe.
            </p><p>
            For more information, see
            <a class="xref" href="replication.html#replication-features-transactions" title="17.5.1.34 Replication and Transactions">Section 17.5.1.34, “Replication and Transactions”</a>.
          </p></li><li class="listitem"><p><b>Accesses or references self-logging tables. </b>
              All reads and writes to self-logging tables are considered
              unsafe. Within a transaction, any statement following a
              read or write to self-logging tables is also considered
              unsafe.
            </p></li><li class="listitem"><p><b>LOAD DATA statements. </b>
              <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> is treated as
              unsafe and when
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=MIXED</code></a> the
              statement is logged in row-based format. When
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a>
              <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> does not generate
              a warning, unlike other unsafe statements.
            </p></li><li class="listitem"><p><b>XA transactions. </b>
              If two XA transactions committed in parallel on the master
              are being prepared on the slave in the inverse order,
              locking dependencies can occur with statement-based
              replication that cannot be safely resolved, and it is
              possible for replication to fail with deadlock on the
              slave. When
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a>
              is set, DML statements inside XA transactions are flagged
              as being unsafe and generate a warning. When
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=MIXED</code></a> or
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a> is set,
              DML statements inside XA transactions are logged using
              row-based replication, and the potential issue is not
              present.
            </p></li><li class="listitem"><p><b><code class="literal">DEFAULT</code> clause that refers to a nondeterministic
              function. </b>
              If an expression default value refers to a
              nondeterministic function, any statement that causes the
              expression to be evaluated is unsafe for statement-based
              replication. This includes statements such as
              <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>,
              <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>, and
              <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a>. Unlike most
              other unsafe statements, this category of statement cannot
              be replicated safely in row-based format. When
              <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
              <code class="literal">STATEMENT</code>, the statement is logged and
              executed but a warning message is written to the error
              log. When <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>
              is set to <code class="literal">MIXED</code> or
              <code class="literal">ROW</code>, the statement is not executed and
              an error message is written to the error log. For more
              information on the handling of explicit defaults, see
              <a class="xref" href="data-types.html#data-types-defaults-explicit" title="Handling of Explicit Defaults as of MySQL 8.0.13">Handling of Explicit Defaults as of MySQL 8.0.13</a>.
</p></li></ul>
</div>
<p>
        For additional information, see
        <a class="xref" href="replication.html#replication-features" title="17.5.1 Replication Features and Issues">Section 17.5.1, “Replication Features and Issues”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-implementation-details"></a>17.2.2 Replication Implementation Details</h3>

</div>

</div>

</div>
<p>
      MySQL replication capabilities are implemented using three
      threads, one on the master server and two on the slave:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Binlog dump thread. </b>
            The master creates a thread to send the binary log contents
            to a slave when the slave connects. This thread can be
            identified in the output of <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
            PROCESSLIST</code></a> on the master as the <code class="literal">Binlog
            Dump</code> thread.
          </p><p>
          The binary log dump thread acquires a lock on the master's
          binary log for reading each event that is to be sent to the
          slave. As soon as the event has been read, the lock is
          released, even before the event is sent to the slave.
        </p></li><li class="listitem"><p><b>Slave I/O thread. </b>
            When a <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement
            is issued on a slave server, the slave creates an I/O
            thread, which connects to the master and asks it to send the
            updates recorded in its binary logs.
          </p><p>
          The slave I/O thread reads the updates that the master's
          <code class="literal">Binlog Dump</code> thread sends (see previous
          item) and copies them to local files that comprise the slave's
          relay log.
        </p><p>
          The state of this thread is shown as
          <code class="literal">Slave_IO_running</code> in the output of
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>.
        </p></li><li class="listitem"><p><b>Slave SQL thread. </b>
            The slave creates an SQL thread to read the relay log that
            is written by the slave I/O thread and execute the events
            contained therein.
</p></li></ul>
</div>
<p>
      In the preceding description, there are three threads per
      master/slave connection. A master that has multiple slaves creates
      one binary log dump thread for each currently connected slave, and
      each slave has its own I/O and SQL threads.
    </p><p>
      A slave uses two threads to separate reading updates from the
      master and executing them into independent tasks. Thus, the task
      of reading statements is not slowed down if statement execution is
      slow. For example, if the slave server has not been running for a
      while, its I/O thread can quickly fetch all the binary log
      contents from the master when the slave starts, even if the SQL
      thread lags far behind. If the slave stops before the SQL thread
      has executed all the fetched statements, the I/O thread has at
      least fetched everything so that a safe copy of the statements is
      stored locally in the slave's relay logs, ready for execution the
      next time that the slave starts.
    </p><p>
      The <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW PROCESSLIST</code></a> statement
      provides information that tells you what is happening on the
      master and on the slave regarding replication. For information on
      master states, see <a class="xref" href="optimization.html#master-thread-states" title="8.14.3 Replication Master Thread States">Section 8.14.3, “Replication Master Thread States”</a>. For
      slave states, see <a class="xref" href="optimization.html#slave-io-thread-states" title="8.14.4 Replication Slave I/O Thread States">Section 8.14.4, “Replication Slave I/O Thread States”</a>, and
      <a class="xref" href="optimization.html#slave-sql-thread-states" title="8.14.5 Replication Slave SQL Thread States">Section 8.14.5, “Replication Slave SQL Thread States”</a>.
    </p><p>
      The following example illustrates how the three threads show up in
      the output from <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW PROCESSLIST</code></a>.
    </p><p>
      On the master server, the output from <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
      PROCESSLIST</code></a> looks like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW PROCESSLIST\G</code></strong>
*************************** 1. row ***************************
     Id: 2
   User: root
   Host: localhost:32931
     db: NULL
Command: Binlog Dump
   Time: 94
  State: Has sent all binlog to slave; waiting for binlog to
         be updated
   Info: NULL
</pre><p>
      Here, thread 2 is a <code class="literal">Binlog Dump</code> replication
      thread that services a connected slave. The
      <code class="literal">State</code> information indicates that all
      outstanding updates have been sent to the slave and that the
      master is waiting for more updates to occur. If you see no
      <code class="literal">Binlog Dump</code> threads on a master server, this
      means that replication is not running; that is, no slaves are
      currently connected.
    </p><p>
      On a slave server, the output from <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
      PROCESSLIST</code></a> looks like this:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW PROCESSLIST\G</code></strong>
*************************** 1. row ***************************
     Id: 10
   User: system user
   Host:
     db: NULL
Command: Connect
   Time: 11
  State: Waiting for master to send event
   Info: NULL
*************************** 2. row ***************************
     Id: 11
   User: system user
   Host:
     db: NULL
Command: Connect
   Time: 11
  State: Has read all relay log; waiting for the slave I/O
         thread to update it
   Info: NULL
</pre><p>
      The <code class="literal">State</code> information indicates that thread 10
      is the I/O thread that is communicating with the master server,
      and thread 11 is the SQL thread that is processing the updates
      stored in the relay logs. At the time that
      <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW PROCESSLIST</code></a> was run, both
      threads were idle, waiting for further updates.
    </p><p>
      The value in the <code class="literal">Time</code> column can show how late
      the slave is compared to the master. See
      <a class="xref" href="faqs.html#faqs-replication" title="A.14 MySQL 8.0 FAQ: Replication">Section A.14, “MySQL 8.0 FAQ: Replication”</a>. If sufficient time elapses on
      the master side without activity on the <code class="literal">Binlog
      Dump</code> thread, the master determines that the slave is no
      longer connected. As for any other client connection, the timeouts
      for this depend on the values of
      <code class="option">net_write_timeout</code> and
      <code class="option">net_retry_count</code>; for more information about
      these, see <a class="xref" href="server-administration.html#server-system-variables" title="5.1.8 Server System Variables">Section 5.1.8, “Server System Variables”</a>.
    </p><p>
      The <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> statement
      provides additional information about replication processing on a
      slave server. See
      <a class="xref" href="replication.html#replication-administration-status" title="17.1.7.1 Checking Replication Status">Section 17.1.7.1, “Checking Replication Status”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-channels"></a>17.2.3 Replication Channels</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#channels-commands-single-channel">17.2.3.1 Commands for Operations on a Single Channel</a></span></dt><dt><span class="section"><a href="replication.html#channels-with-prev-replication">17.2.3.2 Compatibility with Previous Replication Statements</a></span></dt><dt><span class="section"><a href="replication.html#channels-startup-options">17.2.3.3 Startup Options and Replication Channels</a></span></dt><dt><span class="section"><a href="replication.html#channels-naming-conventions">17.2.3.4 Replication Channel Naming Conventions</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444263722480"></a><a class="indexterm" name="idm46444263721408"></a><p>
    In MySQL multi-source replication, a slave opens multiple
    replication channels, one for each master. The replication channels
    represent the path of transactions flowing from a master to the
    slave. Each replication channel has its own receiver (I/O) thread,
    one or more applier (SQL) threads, and relay log. When transactions
    from a master are received by a channel's receiver thread, they
    are added to the channel's relay log file and passed through to
    the channel's applier threads. This enables each channel to function
    independently.
  </p><p>
    This section describes how channels can be used in a replication
    topology, and the impact they have on single-source replication. For
    instructions to configure masters and slaves for multi-source
    replication, to start, stop and reset multi-source slaves, and to
    monitor multi-source replication, see
    <a class="xref" href="replication.html#replication-multi-source" title="17.1.4 MySQL Multi-Source Replication">Section 17.1.4, “MySQL Multi-Source Replication”</a>.
  </p><p>
    The maximum number of channels that can be created on one slave in a
    multi-source replication topology is 256. Each replication channel
    must have a unique (nonempty) name, as explained in
    <a class="xref" href="replication.html#channels-naming-conventions" title="17.2.3.4 Replication Channel Naming Conventions">Section 17.2.3.4, “Replication Channel Naming Conventions”</a>. The error codes and
    messages that are issued when multi-source replication is enabled
    specify the channel that generated the error.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
      Each channel on a multi-source replication slave must replicate
      from a different master. You cannot set up multiple replication
      channels from a single slave to a single master. This is because
      the server IDs of replication slaves must be unique in a
      replication topology. The master distinguishes slaves only by
      their server IDs, not by the names of the replication channels, so
      it cannot recognize different replication channels from the same
      slave.
</p>
</div>
<p>
    A multi-source replication slave can also be set up as a
    multi-threaded replication slave, by setting the
    <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> system
    variable to a value greater than 0. When you do this on a
    multi-source replication slave, each channel on the slave has the
    specified number of applier threads, plus a coordinator thread to
    manage them. You cannot configure the number of applier threads for
    individual channels.
  </p><p>
    From MySQL 8.0, multi-source replication slaves can be configured
    with replication filters on specific replication channels. Channel
    specific replication filters can be used when the same database or
    table is present on multiple masters, and you only need the slave to
    replicate it from one master. For more information, see
    <a class="xref" href="replication.html#replication-rules-channel-based-filters" title="17.2.5.4 Replication Channel Based Filters">Section 17.2.5.4, “Replication Channel Based Filters”</a>.
  </p><p>
    To provide compatibility with previous versions, the MySQL server
    automatically creates on startup a default channel whose name is the
    empty string (<code class="literal">""</code>). This channel is always
    present; it cannot be created or destroyed by the user. If no other
    channels (having nonempty names) have been created, replication
    statements act on the default channel only, so that all replication
    statements from older slaves function as expected (see
    <a class="xref" href="replication.html#channels-with-prev-replication" title="17.2.3.2 Compatibility with Previous Replication Statements">Section 17.2.3.2, “Compatibility with Previous Replication Statements”</a>. Statements
    applying to replication channels as described in this section can be
    used only when there is at least one named channel.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="channels-commands-single-channel"></a>17.2.3.1 Commands for Operations on a Single Channel</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444263707680"></a><a class="indexterm" name="idm46444263706192"></a><p>
      To enable MySQL replication operations to act on individual
      replication channels, use the <code class="literal">FOR CHANNEL
      <em class="replaceable"><code>channel</code></em></code> clause with the
      following replication statements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#show-relaylog-events" title="13.7.7.32 SHOW RELAYLOG EVENTS Statement"><code class="literal">SHOW RELAYLOG EVENTS</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#flush" title="13.7.8.3 FLUSH Statement"><code class="literal">FLUSH RELAY
          LOGS</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a>
</p></li></ul>
</div>
<p>
      An additional <code class="literal">channel</code> parameter is introduced
      for the following function:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="functions.html#function_master-pos-wait"><code class="literal">MASTER_POS_WAIT()</code></a>
</p></li></ul>
</div>
<p>
      The following statements are disallowed for the
      <code class="literal">group_replication_recovery</code> channel:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>
</p></li></ul>
</div>
<p>
      The following statements are disallowed for the
      <code class="literal">group_replication_applier</code> channel:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>
</p></li></ul>
</div>
<p>
      <a class="link" href="sql-statements.html#flush" title="13.7.8.3 FLUSH Statement"><code class="literal">FLUSH RELAY LOGS</code></a>
      is now permitted for the
      <code class="literal">group_replication_applier</code> channel, but if the
      request is received while a transaction is being applied, the
      request is performed after the transaction ends. The requester
      must wait while the transaction is completed and the rotation
      takes place. This behavior prevents transactions from being split,
      which is not permitted for Group Replication.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="channels-with-prev-replication"></a>17.2.3.2 Compatibility with Previous Replication Statements</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444263668400"></a><p>
      When a replication slave has multiple channels and a <code class="literal">FOR
      CHANNEL <em class="replaceable"><code>channel</code></em></code> option is not
      specified, a valid statement generally acts on all available
      channels, with some specific exceptions.
    </p><p>
      For example, the following statements behave as expected for all
      except certain Group Replication channels:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> starts replication
          threads for all channels, except the
          <code class="literal">group_replication_recovery</code> and
          <code class="literal">group_replication_applier</code> channels.
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> stops replication
          threads for all channels, except the
          <code class="literal">group_replication_recovery</code> and
          <code class="literal">group_replication_applier</code> channels.
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> reports the
          status for all channels, except the
          <code class="literal">group_replication_applier</code> channel.
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET
          SLAVE</code></a> resets all channels.
</p></li></ul>
</div>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Warning
</div>
<p>
        Use <code class="literal">RESET SLAVE</code> with caution as this
        statement deletes all existing channels, purges their relay log
        files, and recreates only the default channel.
</p>
</div>
<p>
      Some replication statements cannot operate on all channels. In
      this case, error 1964 <span class="errortext">Multiple channels exist on the
      slave. Please provide channel name as an argument.</span> is
      generated. The following statements and functions generate this
      error when used in a multi-source replication topology and a
      <code class="literal">FOR CHANNEL <em class="replaceable"><code>channel</code></em></code>
      option is not used to specify which channel to act on:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="sql-statements.html#show-relaylog-events" title="13.7.7.32 SHOW RELAYLOG EVENTS Statement"><code class="literal">SHOW RELAYLOG EVENTS</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
        </p></li><li class="listitem"><p>
          <a class="link" href="functions.html#function_master-pos-wait"><code class="literal">MASTER_POS_WAIT()</code></a>
</p></li></ul>
</div>
<p>
      Note that a default channel always exists in a single source
      replication topology, where statements and functions behave as in
      previous versions of MySQL.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="channels-startup-options"></a>17.2.3.3 Startup Options and Replication Channels</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444263640496"></a><a class="indexterm" name="idm46444263639008"></a><p>
      This section describes startup options which are impacted by the
      addition of replication channels.
    </p><p>
      The following startup settings <span class="emphasis"><em>must</em></span> be
      configured correctly to use multi-source replication.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>.
        </p><p>
          This must be set to <code class="literal">TABLE</code>. If this variable
          is set to <code class="literal">FILE</code>, attempting to add more
          sources to a slave fails with
          <a class="link" href="error-handling.html#error_er_slave_new_channel_wrong_repository"><code class="literal">ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY</code></a>.
          The <code class="literal">FILE</code> setting is now deprecated, and
          <code class="literal">TABLE</code> is the default.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository</code></a>
        </p><p>
          This must be set to <code class="literal">TABLE</code>. If this variable
          is set to <code class="literal">FILE</code>, attempting to add more
          sources to a slave fails with
          <a class="link" href="error-handling.html#error_er_slave_new_channel_wrong_repository"><code class="literal">ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY</code></a>.
          The <code class="literal">FILE</code> setting is now deprecated, and
          <code class="literal">TABLE</code> is the default.
</p></li></ul>
</div>
<p>
      The following startup options now affect <span class="emphasis"><em>all</em></span>
      channels in a replication topology.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">--log-slave-updates</code></a>
        </p><p>
          All transactions received by the slave (even from multiple
          sources) are written in the binary log.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_relay_log_purge"><code class="literal">--relay-log-purge</code></a>
        </p><p>
          When set, each channel purges its own relay log automatically.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_slave_transaction_retries"><code class="literal">--slave_transaction_retries</code></a>
        </p><p>
          The specified number of transaction retries can take place on
          all applier threads of all channels.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a>
        </p><p>
          No replication threads start on any channels.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_slave_skip_errors"><code class="literal">--slave-skip-errors</code></a>
        </p><p>
          Execution continues and errors are skipped for all channels.
</p></li></ul>
</div>
<p>
      The values set for the following startup options apply on each
      channel; since these are <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> startup
      options, they are applied on every channel.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="option">--max-relay-log-size=<em class="replaceable"><code>size</code></em></code>
        </p><p>
          Maximum size of the individual relay log file for each
          channel; after reaching this limit, the file is rotated.
        </p></li><li class="listitem"><p>
          <code class="option">--relay-log-space-limit=<em class="replaceable"><code>size</code></em></code>
        </p><p>
          Upper limit for the total size of all relay logs combined, for
          each individual channel. For <em class="replaceable"><code>N</code></em>
          channels, the combined size of these logs is limited to
          <a class="link" href="replication.html#sysvar_relay_log_space_limit"><code class="literal">relay_log_space_limit *
          <em class="replaceable"><code>N</code></em></code></a>.
        </p></li><li class="listitem"><p>
          <code class="option">--slave-parallel-workers=<em class="replaceable"><code>value</code></em></code>
        </p><p>
          Number of slave parallel workers per channel.
        </p></li><li class="listitem"><p>
          <a class="link" href="replication.html#sysvar_slave_checkpoint_group"><code class="literal">slave_checkpoint_group</code></a>
        </p><p>
          Waiting time by an I/O thread for each source.
        </p></li><li class="listitem"><p>
          <code class="option">--relay-log-index=filename</code>
        </p><p>
          Base name for each channel's relay log index file. See
          <a class="xref" href="replication.html#channels-naming-conventions" title="17.2.3.4 Replication Channel Naming Conventions">Section 17.2.3.4, “Replication Channel Naming Conventions”</a>.
        </p></li><li class="listitem"><p>
          <code class="option">--relay-log=filename</code>
        </p><p>
          Denotes the base name of each channel's relay log file.
          See <a class="xref" href="replication.html#channels-naming-conventions" title="17.2.3.4 Replication Channel Naming Conventions">Section 17.2.3.4, “Replication Channel Naming Conventions”</a>.
        </p></li><li class="listitem"><p>
          <code class="option">--slave_net-timeout=N</code>
        </p><p>
          This value is set per channel, so that each channel waits for
          <em class="replaceable"><code>N</code></em> seconds to check for a broken
          connection.
        </p></li><li class="listitem"><p>
          <code class="option">--slave-skip-counter=N</code>
        </p><p>
          This value is set per channel, so that each channel skips
          <em class="replaceable"><code>N</code></em> events from its master.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="channels-naming-conventions"></a>17.2.3.4 Replication Channel Naming Conventions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444263585680"></a><p>
      This section describes how naming conventions are impacted by
      replication channels.
    </p><p>
      Each replication channel has a unique name which is a string with
      a maximum length of 64 characters and is case-insensitive. Because
      channel names are used in slave tables, the character set used for
      these is always UTF-8. Although you are generally free to use any
      name for channels, the following names are reserved:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">group_replication_applier</code>
        </p></li><li class="listitem"><p>
          <code class="literal">group_replication_recovery</code>
</p></li></ul>
</div>
<p>
      The name you choose for a replication channel also influences the
      file names used by a multi-source replication slave. The relay log
      files and index files for each channel are named
      <code class="filename"><em class="replaceable"><code>relay_log_basename</code></em>-<em class="replaceable"><code>channel</code></em>.xxxxxx</code>,
      where <em class="replaceable"><code>relay_log_basename</code></em> is a base name
      specified using the <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a>
      system variable, and <em class="replaceable"><code>channel</code></em> is the
      name of the channel logged to this file. If you do not specify the
      <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable, a
      default file name is used that also includes the name of the
      channel.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="slave-logs"></a>17.2.4 Replication Relay and Status Logs</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#slave-logs-relaylog">17.2.4.1 The Slave Relay Log</a></span></dt><dt><span class="section"><a href="replication.html#slave-logs-status">17.2.4.2 Slave Status Logs</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444263572672"></a><a class="indexterm" name="idm46444263571216"></a><a class="indexterm" name="idm46444263569728"></a><a class="indexterm" name="idm46444263568640"></a><a class="indexterm" name="idm46444263567552"></a><a class="indexterm" name="idm46444263566464"></a><a class="indexterm" name="idm46444263565376"></a><a class="indexterm" name="idm46444263564288"></a><a class="indexterm" name="idm46444263563184"></a><a class="indexterm" name="idm46444263562112"></a><p>
      During replication, a slave server creates several logs that hold
      the binary log events relayed from the master to the slave, and
      record information about the current status and location within
      the relay log. There are three types of logs used in the process,
      listed here:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The <span class="emphasis"><em>relay log</em></span> consists of the events read
          from the binary log of the master and written by the slave I/O
          thread. Events in the relay log are executed on the slave as
          part of the SQL thread.
        </p></li><li class="listitem"><p>
          The <span class="emphasis"><em>master info log</em></span> contains status and
          current configuration information for the slave's
          connection to the master. This log holds information on the
          master host name, login credentials, and coordinates
          indicating how far the slave has read from the master's binary
          log. The master info log is written to the
          <code class="literal">mysql.slave_master_info</code> table.
        </p></li><li class="listitem"><p>
          The <span class="emphasis"><em>relay log info log</em></span> holds status
          information about the execution point within the slave's
          relay log. The relay log is written to the
          <code class="literal">mysql.slave_relay_log_info</code> table.
</p></li></ul>
</div>
<p>
      In MySQL 8.0, a warning is given when
      <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> is unable to initialize the replication
      logging tables, but the slave is allowed to continue starting.
      This situation is most likely to occur when upgrading from a
      version of MySQL that does not support slave logging tables to one
      in which they are supported.
    </p><p>
      In MySQL 8.0, execution of any statement requiring a
      write lock on either or both of the
      <code class="literal">slave_master_info</code> and
      <code class="literal">slave_relay_log_info</code> tables is disallowed while
      replication is ongoing, while statements that perform only reads
      are permitted at any time.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        Do not attempt to update or insert rows in the
        <code class="literal">slave_master_info</code> or
        <code class="literal">slave_relay_log_info</code> tables manually. Doing
        so can cause undefined behavior, and is not supported.
</p>
</div>
<p><a name="replication-implementation-crash-safe"></a><b>Making replication resilient to unexpected halts. </b>
        The <code class="literal">mysql.slave_master_info</code> and
        <code class="literal">mysql.slave_relay_log_info</code> tables are created
        using the transactional storage engine
        <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>. Updates to the relay log
        info log table are committed together with the transactions,
        meaning that the slave's progress information recorded in that
        log is always consistent with what has been applied to the
        database, even in the event of an unexpected server halt. The
        <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a> option must
        be enabled on the slave to guarantee resilience. For more
        details, see
        <a class="xref" href="replication.html#replication-solutions-unexpected-slave-halt" title="17.4.2 Handling an Unexpected Halt of a Replication Slave">Section 17.4.2, “Handling an Unexpected Halt of a Replication Slave”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="slave-logs-relaylog"></a>17.2.4.1 The Slave Relay Log</h4>
</div>
</div>
</div>
<p>
        The relay log, like the binary log, consists of a set of
        numbered files containing events that describe database changes,
        and an index file that contains the names of all used relay log
        files. The default location for relay log files is the data
        directory.
      </p><p>
        The term <span class="quote">“<span class="quote">relay log file</span>”</span> generally denotes an
        individual numbered file containing database events. The term
        <span class="quote">“<span class="quote">relay log</span>”</span> collectively denotes the set of
        numbered relay log files plus the index file.
      </p><p>
        Relay log files have the same format as binary log files and can
        be read using <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> (see
        <a class="xref" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files">Section 4.6.8, “<span class="command"><strong>mysqlbinlog</strong></span> — Utility for Processing Binary Log Files”</a>). If binary log transaction
        compression (available as of MySQL 8.0.20) is in use,
        transaction payloads written to the relay log are compressed in
        the same way as for the binary log. For more information on
        binary log transaction compression, see
        <a class="xref" href="server-administration.html#binary-log-transaction-compression" title="5.4.4.5 Binary Log Transaction Compression">Section 5.4.4.5, “Binary Log Transaction Compression”</a>.
      </p><p>
        For the default replication channel, relay log file names have
        the default form
        <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin.<em class="replaceable"><code>nnnnnn</code></em></code>,
        where <em class="replaceable"><code>host_name</code></em> is the name of the
        slave server host and <em class="replaceable"><code>nnnnnn</code></em> is a
        sequence number. Successive relay log files are created using
        successive sequence numbers, beginning with
        <code class="literal">000001</code>. For non-default replication channels,
        the default base name is
        <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin-<em class="replaceable"><code>channel</code></em></code>,
        where <em class="replaceable"><code>channel</code></em> is the name of the
        replication channel recorded in the relay log.
      </p><p>
        The slave uses an index file to track the relay log files
        currently in use. The default relay log index file name is
        <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin.index</code>
        for the default channel, and
        <code class="filename"><em class="replaceable"><code>host_name</code></em>-relay-bin-<em class="replaceable"><code>channel</code></em>.index</code>
        for non-default replication channels.
      </p><p>
        The default relay log file and relay log index file names and
        locations can be overridden with, respectively, the
        <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> and
        <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
        variables (see <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>).
      </p><p>
        If a slave uses the default host-based relay log file names,
        changing a slave's host name after replication has been set up
        can cause replication to fail with the errors <span class="errortext">Failed
        to open the relay log</span> and <span class="errortext">Could not find
        target log during relay log initialization</span>. This is
        a known issue (see Bug #2122). If you anticipate that a slave's
        host name might change in the future (for example, if networking
        is set up on the slave such that its host name can be modified
        using DHCP), you can avoid this issue entirely by using the
        <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> and
        <a class="link" href="replication.html#sysvar_relay_log_index"><code class="literal">relay_log_index</code></a> system
        variables to specify relay log file names explicitly when you
        initially set up the slave. This will make the names independent
        of server host name changes.
      </p><p>
        If you encounter the issue after replication has already begun,
        one way to work around it is to stop the slave server, prepend
        the contents of the old relay log index file to the new one, and
        then restart the slave. On a Unix system, this can be done as
        shown here:
      </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>cat <em class="replaceable"><code>new_relay_log_name</code></em>.index &gt;&gt; <em class="replaceable"><code>old_relay_log_name</code></em>.index</code></strong>
shell&gt; <strong class="userinput"><code>mv <em class="replaceable"><code>old_relay_log_name</code></em>.index <em class="replaceable"><code>new_relay_log_name</code></em>.index</code></strong>
</pre><p>
        A slave server creates a new relay log file under the following
        conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Each time the I/O thread starts.
          </p></li><li class="listitem"><p>
            When the logs are flushed (for example, with
            <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH LOGS</code></a> or
            <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin flush-logs</strong></span></a>).
          </p></li><li class="listitem"><p>
            When the size of the current relay log file becomes too
            large, which is determined as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                If the value of
                <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> is
                greater than 0, that is the maximum relay log file size.
              </p></li><li class="listitem"><p>
                If the value of
                <a class="link" href="replication.html#sysvar_max_relay_log_size"><code class="literal">max_relay_log_size</code></a> is
                0, <a class="link" href="replication.html#sysvar_max_binlog_size"><code class="literal">max_binlog_size</code></a>
                determines the maximum relay log file size.
</p></li></ul>
</div>
</li></ul>
</div>
<p>
        The SQL thread automatically deletes each relay log file after
        it has executed all events in the file and no longer needs it.
        There is no explicit mechanism for deleting relay logs because
        the SQL thread takes care of doing so. However,
        <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH LOGS</code></a> rotates relay logs,
        which influences when the SQL thread deletes them.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="slave-logs-status"></a>17.2.4.2 Slave Status Logs</h4>

</div>

</div>

</div>
<p>
        A replication slave server creates two slave status logs in the
        form of <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> tables in the
        <code class="literal">mysql</code> system schema: the master info log
        <code class="literal">slave_master_info</code>, and the relay log info log
        <code class="literal">slave_relay_log_info</code>.
      </p><p>
        The two slave status logs contain information similar to that
        shown in the output of the <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
        STATUS</code></a> statement, which is discussed in
        <a class="xref" href="sql-statements.html#replication-statements-slave" title="13.4.2 SQL Statements for Controlling Slave Servers">Section 13.4.2, “SQL Statements for Controlling Slave Servers”</a>. The slave status
        logs survive a slave server's shutdown. The next time the
        slave starts, it reads the two logs to determine how far it
        previously proceeded in reading binary logs from the master and
        in processing its own relay logs.
      </p><p>
        Access privileges for the master info log table should be
        restricted because it contains the password for connecting to
        the master. See <a class="xref" href="security.html#password-logging" title="6.1.2.3 Passwords and Logging">Section 6.1.2.3, “Passwords and Logging”</a>.
      </p><p>
        <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> clears the data in
        the <code class="literal">slave_master_info</code> and
        <code class="literal">slave_relay_log_info</code> tables, with the
        exception of replication connection parameters (depending on the
        MySQL Server release). For details, see the description for
        <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a>.
      </p><p>
        Before MySQL 8.0, to create the slave status logs as tables, it
        was necessary to specify
        <a class="link" href="replication.html#sysvar_master_info_repository"><code class="literal">master_info_repository=TABLE</code></a>
        and
        <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=TABLE</code></a>,
        at server startup. Otherwise, the logs were created as files in
        the data directory named <code class="filename">master.info</code> and
        <code class="filename">relay-log.info</code>, or with alternative names
        and locations specified by the
        <a class="link" href="replication.html#option_mysqld_master-info-file"><code class="option">--master-info-file</code></a> option and
        <a class="link" href="replication.html#sysvar_relay_log_info_file"><code class="literal">relay_log_info_file</code></a> system
        variable. From MySQL 8.0, creating the slave status logs as
        tables is the default, and creating the slave status logs as
        files is deprecated. Note that when the slave status logs are
        created as tables, they are copied to the recipient during a
        cloning operation, but when they are created as files, they are
        not copied. For more information, see
        <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.
      </p><p>
        The <code class="literal">mysql.slave_master_info</code> and
        <code class="literal">mysql.slave_relay_log_info</code> tables are created
        using the <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> transactional
        storage engine. Updates to the relay log info log table are
        committed together with the transactions, meaning that the
        slave's progress information recorded in that log is always
        consistent with what has been applied to the database, even in
        the event of an unexpected server halt. The
        <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a> option must
        be enabled on the slave to guarantee resilience. For more
        details, see
        <a class="xref" href="replication.html#replication-solutions-unexpected-slave-halt" title="17.4.2 Handling an Unexpected Halt of a Replication Slave">Section 17.4.2, “Handling an Unexpected Halt of a Replication Slave”</a>.
      </p><p>
        One additional slave status log is created primarily for
        internal use, and holds status information about worker threads
        on a multithreaded replication slave. This slave worker log
        includes the names and positions for the relay log file and
        master binary log file for each worker thread. If the relay log
        info log for the slave is created as a table, which is the
        default, the slave worker log is written to the
        <code class="literal">mysql.slave_worker_info</code> table. If the relay
        log info log is written to a file, the slave worker log is
        written to the <code class="filename">worker-relay-log.info</code> file.
        For external use, status information for worker threads is
        presented in the Performance Schema
        <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>
        table.
      </p><p>
        The slave I/O thread updates the master info log. The following
        table shows the correspondence between the columns in the
        <code class="literal">mysql.slave_master_info</code> table, the columns
        displayed by <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>,
        and the lines in the deprecated <code class="filename">master.info</code>
        file.
</p>
<div class="informaltable">
<table summary="The correspondence between the columns in the mysql.slave_master_info table, the columns displayed by SHOW SLAVE STATUS, and the lines in the deprecated master.info file."><col width="31%"><col width="40%"><col width="16%"><col width="18%"><thead><tr>
            <th scope="col"><code class="literal">slave_master_info</code> Table Column</th>
            <th scope="col"><code class="literal">SHOW SLAVE STATUS</code> Column</th>
            <th scope="col"><code class="filename">master.info</code> File Line</th>
            <th scope="col">Description</th>
          </tr></thead><tbody><tr>
            <td scope="row"><code class="literal">Number_of_lines</code></td>
            <td>[None]</td>
            <td>1</td>
            <td>Number of columns in the table (or lines in the file)</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_log_name</code></td>
            <td><code class="literal">Master_Log_File</code></td>
            <td>2</td>
            <td>The name of the master binary log currently being read from the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_log_pos</code></td>
            <td><code class="literal">Read_Master_Log_Pos</code></td>
            <td>3</td>
            <td>The current position within the master binary log that has been read
              from the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Host</code></td>
            <td><code class="literal">Master_Host</code></td>
            <td>4</td>
            <td>The host name of the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">User_name</code></td>
            <td><code class="literal">Master_User</code></td>
            <td>5</td>
            <td>The user name used to connect to the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">User_password</code></td>
            <td>Password (not shown by <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>)</td>
            <td>6</td>
            <td>The password used to connect to the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Port</code></td>
            <td><code class="literal">Master_Port</code></td>
            <td>7</td>
            <td>The network port used to connect to the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Connect_retry</code></td>
            <td><code class="literal">Connect_Retry</code></td>
            <td>8</td>
            <td>The period (in seconds) that the slave will wait before trying to
              reconnect to the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Enabled_ssl</code></td>
            <td><code class="literal">Master_SSL_Allowed</code></td>
            <td>9</td>
            <td>Indicates whether the server supports SSL connections</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_ca</code></td>
            <td><code class="literal">Master_SSL_CA_File</code></td>
            <td>10</td>
            <td>The file used for the Certificate Authority (CA) certificate</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_capath</code></td>
            <td><code class="literal">Master_SSL_CA_Path</code></td>
            <td>11</td>
            <td>The path to the Certificate Authority (CA) certificates</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_cert</code></td>
            <td><code class="literal">Master_SSL_Cert</code></td>
            <td>12</td>
            <td>The name of the SSL certificate file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_cipher</code></td>
            <td><code class="literal">Master_SSL_Cipher</code></td>
            <td>13</td>
            <td>The list of possible ciphers used in the handshake for the SSL
              connection</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_key</code></td>
            <td><code class="literal">Master_SSL_Key</code></td>
            <td>14</td>
            <td>The name of the SSL key file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_verify_server_cert</code></td>
            <td><code class="literal">Master_SSL_Verify_Server_Cert</code></td>
            <td>15</td>
            <td>Whether to verify the server certificate</td>
          </tr><tr>
            <td scope="row"><code class="literal">Heartbeat</code></td>
            <td>[None]</td>
            <td>16</td>
            <td>Interval between replication heartbeats, in seconds</td>
          </tr><tr>
            <td scope="row"><code class="literal">Bind</code></td>
            <td><code class="literal">Master_Bind</code></td>
            <td>17</td>
            <td>Which of the slave's network interfaces should be used for
              connecting to the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ignored_server_ids</code></td>
            <td><code class="literal">Replicate_Ignore_Server_Ids</code></td>
            <td>18</td>
            <td>The list of server IDs to be ignored. Note that for
              <code class="literal">Ignored_server_ids</code> the list of server
              IDs is preceded by the total number of server IDs to
              ignore.</td>
          </tr><tr>
            <td scope="row"><code class="literal">Uuid</code></td>
            <td><code class="literal">Master_UUID</code></td>
            <td>19</td>
            <td>The master's unique ID</td>
          </tr><tr>
            <td scope="row"><code class="literal">Retry_count</code></td>
            <td><code class="literal">Master_Retry_Count</code></td>
            <td>20</td>
            <td>Maximum number of reconnection attempts permitted</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_crl</code></td>
            <td>[None]</td>
            <td>21</td>
            <td>Path to an SSL certificate revocation-list file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Ssl_crlpath</code></td>
            <td>[None]</td>
            <td>22</td>
            <td>Path to a directory containing SSL certificate revocation-list files</td>
          </tr><tr>
            <td scope="row"><code class="literal">Enabled_auto_position</code></td>
            <td><code class="literal">Auto_position</code></td>
            <td>23</td>
            <td>If autopositioning is in use or not</td>
          </tr><tr>
            <td scope="row"><code class="literal">Channel_name</code></td>
            <td><code class="literal">Channel_name</code></td>
            <td>24</td>
            <td>The name of the replication channel</td>
          </tr><tr>
            <td scope="row"><code class="literal">Tls_version</code></td>
            <td><code class="literal">Master_TLS_Version</code></td>
            <td>25</td>
            <td>TLS version on master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Public_key_path</code></td>
            <td><code class="literal">Master_public_key_path</code></td>
            <td>26</td>
            <td>Name of RSA public key file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Get_public_key</code></td>
            <td><code class="literal">Get_master_public_key</code></td>
            <td>27</td>
            <td>Whether to request RSA public key from master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_compression_algorithm</code></td>
            <td>[None]</td>
            <td>28</td>
            <td>Permitted compression algorithms</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_zstd_compression_level</code></td>
            <td>[None]</td>
            <td>29</td>
            <td><code class="literal">zstd</code> compression level</td>
          </tr><tr>
            <td scope="row"><code class="literal">Tls_ciphersuites</code></td>
            <td>[None]</td>
            <td>30</td>
            <td>Permitted ciphersuites for TLSv1.3</td>
</tr></tbody></table>
</div>
<p>
        The slave SQL thread updates the relay log info log. The
        following table shows the correspondence between the columns in
        the <code class="literal">mysql.slave_relay_log_info</code> table, the
        columns displayed by <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
        STATUS</code></a>, and the lines in the deprecated
        <code class="filename">relay-log.info</code> file.
</p>
<div class="informaltable">
<table summary="The correspondence between the columns in the mysql.slave_relay_log_info table, the columns displayed by SHOW SLAVE STATUS, and the lines in the deprecated relay-log.info file."><col width="30%"><col width="40%"><col width="15%"><col width="20%"><thead><tr>
            <th scope="col"><code class="literal">slave_relay_log_info</code> Table Column</th>
            <th scope="col"><code class="literal">SHOW SLAVE STATUS</code> Column</th>
            <th scope="col">Line in <code class="filename">relay-log.info</code> File</th>
            <th scope="col">Description</th>
          </tr></thead><tbody><tr>
            <td scope="row"><code class="literal">Number_of_lines</code></td>
            <td>[None]</td>
            <td>1</td>
            <td>Number of columns in the table or lines in the file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Relay_log_name</code></td>
            <td><code class="literal">Relay_Log_File</code></td>
            <td>2</td>
            <td>The name of the current relay log file</td>
          </tr><tr>
            <td scope="row"><code class="literal">Relay_log_pos</code></td>
            <td><code class="literal">Relay_Log_Pos</code></td>
            <td>3</td>
            <td>The current position within the relay log file; events up to this
              position have been executed on the slave database</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_log_name</code></td>
            <td><code class="literal">Relay_Master_Log_File</code></td>
            <td>4</td>
            <td>The name of the master binary log file from which the events in the
              relay log file were read</td>
          </tr><tr>
            <td scope="row"><code class="literal">Master_log_pos</code></td>
            <td><code class="literal">Exec_Master_Log_Pos</code></td>
            <td>5</td>
            <td>The equivalent position within the master's binary log file of events
              that have already been executed</td>
          </tr><tr>
            <td scope="row"><code class="literal">Sql_delay</code></td>
            <td><code class="literal">SQL_Delay</code></td>
            <td>6</td>
            <td>The number of seconds that the slave must lag the master</td>
          </tr><tr>
            <td scope="row"><code class="literal">Number_of_workers</code></td>
            <td>[None]</td>
            <td>7</td>
            <td>The number of slave applier threads for executing replication events
              (transactions) in parallel</td>
          </tr><tr>
            <td scope="row"><code class="literal">Id</code></td>
            <td>[None]</td>
            <td>8</td>
            <td>ID used for internal purposes; currently this is always 1</td>
          </tr><tr>
            <td scope="row"><code class="literal">Channel_name</code></td>
            <td><code class="literal">Channel_name</code></td>
            <td>9</td>
            <td>The name of the replication channel</td>
          </tr><tr>
            <td scope="row"><code class="literal">Privilege_checks_username</code></td>
            <td>[None]</td>
            <td>10</td>
            <td>The user name for the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
              for the channel</td>
          </tr><tr>
            <td scope="row"><code class="literal">Privilege_checks_hostname</code></td>
            <td>[None]</td>
            <td>11</td>
            <td>The host name for the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
              for the channel</td>
          </tr><tr>
            <td scope="row"><code class="literal">Require_row_format</code></td>
            <td>[None]</td>
            <td>12</td>
            <td>Whether the channel accepts only row-based events</td>
          </tr><tr>
            <td scope="row"><code class="literal">Require_table_primary_key_check</code></td>
            <td>[None]</td>
            <td>13</td>
            <td>The channel's policy on whether tables must have primary keys for
              <code class="literal">CREATE TABLE</code> and <code class="literal">ALTER
              TABLE</code> operations</td>
</tr></tbody></table>
</div>
<p>
        When you back up the replication slave's data, ensure that you
        back up the <code class="literal">mysql.slave_master_info</code> and
        <code class="literal">mysql.slave_relay_log_info</code> tables containing
        the slave status logs, because they are needed to resume
        replication after you restore the data from the slave. If you
        lose the relay log files, but still have the relay log info log,
        you can check it to determine how far the SQL thread has
        executed in the master binary logs. Then you can use
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> with the
        <code class="literal">MASTER_LOG_FILE</code> and
        <code class="literal">MASTER_LOG_POS</code> options to tell the slave to
        re-read the binary logs from that point. Of course, this
        requires that the binary logs still exist on the master.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-rules"></a>17.2.5 How Servers Evaluate Replication Filtering Rules</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-rules-db-options">17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options</a></span></dt><dt><span class="section"><a href="replication.html#replication-rules-table-options">17.2.5.2 Evaluation of Table-Level Replication Options</a></span></dt><dt><span class="section"><a href="replication.html#replication-rules-examples">17.2.5.3 Replication Rule Application</a></span></dt><dt><span class="section"><a href="replication.html#replication-rules-channel-based-filters">17.2.5.4 Replication Channel Based Filters</a></span></dt></dl>
</div>
<p>
      If a master server does not write a statement to its binary log,
      the statement is not replicated. If the server does log the
      statement, the statement is sent to all slaves and each slave
      determines whether to execute it or ignore it.
    </p><p>
      On the master, you can control which databases to log changes for
      by using the <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> and
      <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a> options to
      control binary logging. For a description of the rules that
      servers use in evaluating these options, see
      <a class="xref" href="replication.html#replication-rules-db-options" title="17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options">Section 17.2.5.1, “Evaluation of Database-Level Replication and Binary Logging Options”</a>. You should not use
      these options to control which databases and tables are
      replicated. Instead, use filtering on the slave to control the
      events that are executed on the slave.
    </p><p>
      On the slave side, decisions about whether to execute or ignore
      statements received from the master are made according to the
      <code class="option">--replicate-*</code> options that the slave was started
      with. (See <a class="xref" href="replication.html#replication-options" title="17.1.6 Replication and Binary Logging Options and Variables">Section 17.1.6, “Replication and Binary Logging Options and Variables”</a>.) The filters
      governed by these options can also be set dynamically using the
      <code class="literal">CHANGE REPLICATION FILTER</code> statement. The rules
      governing such filters are the same whether they are created on
      startup using <code class="option">--replicate-*</code> options or while the
      slave server is running by <code class="literal">CHANGE REPLICATION
      FILTER</code>. Note that replication filters cannot be used on
      Group Replication-specific channels on a MySQL server instance
      that is configured for Group Replication, because filtering
      transactions on some servers would make the group unable to reach
      agreement on a consistent state.
    </p><p>
      In the simplest case, when there are no
      <code class="option">--replicate-*</code> options, the slave executes all
      statements that it receives from the master. Otherwise, the result
      depends on the particular options given.
    </p><p>
      Database-level options
      (<a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>,
      <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>) are checked
      first; see <a class="xref" href="replication.html#replication-rules-db-options" title="17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options">Section 17.2.5.1, “Evaluation of Database-Level Replication and Binary Logging Options”</a>, for a
      description of this process. If no database-level options are
      used, option checking proceeds to any table-level options that may
      be in use (see <a class="xref" href="replication.html#replication-rules-table-options" title="17.2.5.2 Evaluation of Table-Level Replication Options">Section 17.2.5.2, “Evaluation of Table-Level Replication Options”</a>,
      for a discussion of these). If one or more database-level options
      are used but none are matched, the statement is not replicated.
    </p><p>
      For statements affecting databases only (that is,
      <a class="link" href="sql-statements.html#create-database" title="13.1.12 CREATE DATABASE Statement"><code class="literal">CREATE DATABASE</code></a>,
      <a class="link" href="sql-statements.html#drop-database" title="13.1.24 DROP DATABASE Statement"><code class="literal">DROP DATABASE</code></a>, and
      <a class="link" href="sql-statements.html#alter-database" title="13.1.2 ALTER DATABASE Statement"><code class="literal">ALTER DATABASE</code></a>), database-level
      options always take precedence over any
      <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a> options.
      In other words, for such statements,
      <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a> options
      are checked if and only if there are no database-level options
      that apply.
    </p><p>
      To make it easier to determine what effect an option set will
      have, it is recommended that you avoid mixing <span class="quote">“<span class="quote">do</span>”</span>
      and <span class="quote">“<span class="quote">ignore</span>”</span> options, or wildcard and nonwildcard
      options.
    </p><p>
      If any <a class="link" href="replication.html#option_mysqld_replicate-rewrite-db"><code class="option">--replicate-rewrite-db</code></a>
      options were specified, they are applied before the
      <code class="option">--replicate-*</code> filtering rules are tested.
</p><a class="indexterm" name="idm46444263192656"></a><a class="indexterm" name="idm46444263191152"></a>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
        All replication filtering options follow the same rules for case
        sensitivity that apply to names of databases and tables
        elsewhere in the MySQL server, including the effects of the
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> system
        variable.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rules-db-options"></a>17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options</h4>

</div>

</div>

</div>
<p>
        When evaluating replication options, the slave begins by
        checking to see whether there are any
        <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> or
        <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> options
        that apply. When using
        <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> or
        <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a>, the process
        is similar, but the options are checked on the master.
      </p><p>
        The database that is checked for a match depends on the binary
        log format of the statement that is being handled. If the
        statement has been logged using the row format, the database
        where data is to be changed is the database that is checked. If
        the statement has been logged using the statement format, the
        default database (specified with a
        <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement) is the database
        that is checked.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          Only DML statements can be logged using the row format. DDL
          statements are always logged as statements, even when
          <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>. All DDL
          statements are therefore always filtered according to the
          rules for statement-based replication. This means that you
          must select the default database explicitly with a
          <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement in order for a
          DDL statement to be applied.
</p>
</div>
<p>
        For replication, the steps involved are listed here:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Which logging format is used?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>STATEMENT. </b>
                  Test the default database.
                </p></li><li class="listitem"><p><b>ROW. </b>
                  Test the database affected by the changes.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the database match any of them?

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                          Continue to Step 4.
                        </p></li><li class="listitem"><p><b>No. </b>
                          Ignore the update and exit.
</p></li></ul>
</div>
<p>
                </p></li><li class="listitem"><p><b>No. </b>
                  Continue to step 3.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the database match any of them?

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                          Ignore the update and exit.
                        </p></li><li class="listitem"><p><b>No. </b>
                          Continue to step 4.
</p></li></ul>
</div>
<p>
                </p></li><li class="listitem"><p><b>No. </b>
                  Continue to step 4.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Proceed to checking the table-level replication options, if
            there are any. For a description of how these options are
            checked, see
            <a class="xref" href="replication.html#replication-rules-table-options" title="17.2.5.2 Evaluation of Table-Level Replication Options">Section 17.2.5.2, “Evaluation of Table-Level Replication Options”</a>.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
              A statement that is still permitted at this stage is not
              yet actually executed. The statement is not executed until
              all table-level options (if any) have also been checked,
              and the outcome of that process permits execution of the
              statement.
</p>
</div>
</li></ol>
</div>
<p>
        For binary logging, the steps involved are listed here:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Are there any <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a>
            or <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Continue to step 2.
                </p></li><li class="listitem"><p><b>No. </b>
                  Log the statement and exit.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Is there a default database (has any database been selected
            by <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a>)?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Continue to step 3.
                </p></li><li class="listitem"><p><b>No. </b>
                  Ignore the statement and exit.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            There is a default database. Are there any
            <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Do any of them match the database?

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                          Log the statement and exit.
                        </p></li><li class="listitem"><p><b>No. </b>
                          Ignore the statement and exit.
</p></li></ul>
</div>
<p>
                </p></li><li class="listitem"><p><b>No. </b>
                  Continue to step 4.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Do any of the
            <a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a> options
            match the database?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Ignore the statement and exit.
                </p></li><li class="listitem"><p><b>No. </b>
                  Log the statement and exit.
</p></li></ul>
</div>
</li></ol>
</div>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Important
</div>
<p>
          For statement-based logging, an exception is made in the rules
          just given for the <a class="link" href="sql-statements.html#create-database" title="13.1.12 CREATE DATABASE Statement"><code class="literal">CREATE
          DATABASE</code></a>, <a class="link" href="sql-statements.html#alter-database" title="13.1.2 ALTER DATABASE Statement"><code class="literal">ALTER
          DATABASE</code></a>, and <a class="link" href="sql-statements.html#drop-database" title="13.1.24 DROP DATABASE Statement"><code class="literal">DROP
          DATABASE</code></a> statements. In those cases, the database
          being <span class="emphasis"><em>created, altered, or dropped</em></span>
          replaces the default database when determining whether to log
          or ignore updates.
</p>
</div>
<p>
        <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db</code></a> can sometimes mean
        <span class="quote">“<span class="quote">ignore other databases</span>”</span>. For example, when using
        statement-based logging, a server running with only
        <a class="link" href="replication.html#option_mysqld_binlog-do-db"><code class="option">--binlog-do-db=sales</code></a> does not
        write to the binary log statements for which the default
        database differs from <code class="literal">sales</code>. When using
        row-based logging with the same option, the server logs only
        those updates that change data in <code class="literal">sales</code>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rules-table-options"></a>17.2.5.2 Evaluation of Table-Level Replication Options</h4>

</div>

</div>

</div>
<p>
        The slave checks for and evaluates table options only if either
        of the following two conditions is true:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            No matching database options were found.
          </p></li><li class="listitem"><p>
            One or more database options were found, and were evaluated
            to arrive at an <span class="quote">“<span class="quote">execute</span>”</span> condition according
            to the rules described in the previous section (see
            <a class="xref" href="replication.html#replication-rules-db-options" title="17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options">Section 17.2.5.1, “Evaluation of Database-Level Replication and Binary Logging Options”</a>).
</p></li></ul>
</div>
<p>
        First, as a preliminary condition, the slave checks whether
        statement-based replication is enabled. If so, and the statement
        occurs within a stored function, the slave executes the
        statement and exits. If row-based replication is enabled, the
        slave does not know whether a statement occurred within a stored
        function on the master, so this condition does not apply.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          For statement-based replication, replication events represent
          statements (all changes making up a given event are associated
          with a single SQL statement); for row-based replication, each
          event represents a change in a single table row (thus a single
          statement such as <code class="literal">UPDATE mytable SET mycol =
          1</code> may yield many row-based events). When viewed in
          terms of events, the process of checking table options is the
          same for both row-based and statement-based replication.
</p>
</div>
<p>
        Having reached this point, if there are no table options, the
        slave simply executes all events. If there are any
        <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> or
        <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
        options, the event must match one of these if it is to be
        executed; otherwise, it is ignored. If there are any
        <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a> or
        <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
        options, all events are executed except those that match any of
        these options.
      </p><p>
        The following steps describe this evaluation in more detail. The
        starting point is the end of the evaluation of the
        database-level options, as described in
        <a class="xref" href="replication.html#replication-rules-db-options" title="17.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options">Section 17.2.5.1, “Evaluation of Database-Level Replication and Binary Logging Options”</a>.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Are there any table replication options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Continue to step 2.
                </p></li><li class="listitem"><p><b>No. </b>
                  Execute the update and exit.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Which logging format is used?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>STATEMENT. </b>
                  Carry out the remaining steps for each statement that
                  performs an update.
                </p></li><li class="listitem"><p><b>ROW. </b>
                  Carry out the remaining steps for each update of a
                  table row.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the table match any of them?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                      Execute the update and exit.
                    </p></li><li class="listitem"><p><b>No. </b>
                      Continue to step 4.
</p></li></ul>
</div>
</li><li class="listitem"><p><b>No. </b>
                  Continue to step 4.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the table match any of them?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                      Ignore the update and exit.
                    </p></li><li class="listitem"><p><b>No. </b>
                      Continue to step 5.
</p></li></ul>
</div>
</li><li class="listitem"><p><b>No. </b>
                  Continue to step 5.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the table match any of them?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                      Execute the update and exit.
                    </p></li><li class="listitem"><p><b>No. </b>
                      Continue to step 6.
</p></li></ul>
</div>
</li><li class="listitem"><p><b>No. </b>
                  Continue to step 6.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Does the table match any of them?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Yes. </b>
                      Ignore the update and exit.
                    </p></li><li class="listitem"><p><b>No. </b>
                      Continue to step 7.
</p></li></ul>
</div>
</li><li class="listitem"><p><b>No. </b>
                  Continue to step 7.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Is there another table to be tested?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Go back to step 3.
                </p></li><li class="listitem"><p><b>No. </b>
                  Continue to step 8.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Are there any
            <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> or
            <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
            options?
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Yes. </b>
                  Ignore the update and exit.
                </p></li><li class="listitem"><p><b>No. </b>
                  Execute the update and exit.
</p></li></ul>
</div>
</li></ol>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          Statement-based replication stops if a single SQL statement
          operates on both a table that is included by a
          <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> or
          <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
          option, and another table that is ignored by a
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a> or
          <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
          option. The slave must either execute or ignore the complete
          statement (which forms a replication event), and it cannot
          logically do this. This also applies to row-based replication
          for DDL statements, because DDL statements are always logged
          as statements, without regard to the logging format in effect.
          The only type of statement that can update both an included
          and an ignored table and still be replicated successfully is a
          DML statement that has been logged with
          <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rules-examples"></a>17.2.5.3 Replication Rule Application</h4>

</div>

</div>

</div>
<p>
        This section provides additional explanation and examples of
        usage for different combinations of replication filtering
        options.
      </p><p>
        Some typical combinations of replication filter rule types are
        given in the following table:
</p>
<div class="informaltable">
<table summary="Typical combinations of replication filter rule types and the outcome of each."><col width="40%"><col width="60%"><thead><tr>
            <th scope="col">Condition (Types of Options)</th>
            <th scope="col">Outcome</th>
          </tr></thead><tbody><tr>
            <td scope="row">No <code class="option">--replicate-*</code> options at all:</td>
            <td>The slave executes all events that it receives from the master.</td>
          </tr><tr>
            <td scope="row"><code class="option">--replicate-*-db</code> options, but no table options:</td>
            <td>The slave accepts or ignores events using the database options. It
              executes all events permitted by those options because
              there are no table restrictions.</td>
          </tr><tr>
            <td scope="row"><code class="option">--replicate-*-table</code> options, but no database options:</td>
            <td>All events are accepted at the database-checking stage because there are
              no database conditions. The slave executes or ignores
              events based solely on the table options.</td>
          </tr><tr>
            <td scope="row">A combination of database and table options:</td>
            <td>The slave accepts or ignores events using the database options. Then it
              evaluates all events permitted by those options according
              to the table options. This can sometimes lead to results
              that seem counterintuitive, and that may be different
              depending on whether you are using statement-based or
              row-based replication; see the text for an example.</td>
</tr></tbody></table>
</div>
<p>
        A more complex example follows, in which we examine the outcomes
        for both statement-based and row-based settings.
      </p><p>
        Suppose that we have two tables <code class="literal">mytbl1</code> in
        database <code class="literal">db1</code> and <code class="literal">mytbl2</code> in
        database <code class="literal">db2</code> on the master, and the slave is
        running with the following options (and no other replication
        filtering options):
      </p><pre data-lang="ini" class="programlisting">replicate-ignore-db = db1
replicate-do-table  = db2.tbl2</pre><p>
        Now we execute the following statements on the master:
      </p><pre data-lang="sql" class="programlisting">USE db1;
INSERT INTO db2.tbl2 VALUES (1);</pre><p>
        The results on the slave vary considerably depending on the
        binary log format, and may not match initial expectations in
        either case.
      </p><p><b>Statement-based replication. </b>
          The <code class="literal">USE</code> statement causes
          <code class="literal">db1</code> to be the default database. Thus the
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> option
          matches, <span class="emphasis"><em>and the
          <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statement is
          ignored</em></span>. The table options are not checked.
        </p><p><b>Row-based replication. </b>
          The default database has no effect on how the slave reads
          database options when using row-based replication. Thus, the
          <a class="link" href="sql-statements.html#use" title="13.8.4 USE Statement"><code class="literal">USE</code></a> statement makes no
          difference in how the
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a> option is
          handled: the database specified by this option does not match
          the database where the <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>
          statement changes data, so the slave proceeds to check the
          table options. The table specified by
          <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a> matches
          the table to be updated, <span class="emphasis"><em>and the row is
          inserted</em></span>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-rules-channel-based-filters"></a>17.2.5.4 Replication Channel Based Filters</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444262993408"></a><p>
        This section explains how to work with replication filters when
        multiple replication channels exist, for example in a
        multi-source replication topology. Before MySQL 8.0, replication
        filters were global, so filters were applied to all replication
        channels. From MySQL 8.0, replication filters can be global or
        channel specific, enabling you to configure multi-source
        replication slaves with replication filters on specific
        replication channels. Channel specific replication filters are
        particularly useful in a multi-source replication topology when
        the same database or table is present on multiple masters, and
        the slave is only required to replicate it from one master.
      </p><p>
        For instructions to set up replication channels, see
        <a class="xref" href="replication.html#replication-multi-source" title="17.1.4 MySQL Multi-Source Replication">Section 17.1.4, “MySQL Multi-Source Replication”</a>, and for more
        information on how they work, see
        <a class="xref" href="replication.html#replication-channels" title="17.2.3 Replication Channels">Section 17.2.3, “Replication Channels”</a>.

        
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          Each channel on a multi-source replication slave must
          replicate from a different master. You cannot set up multiple
          replication channels from a single slave to a single master,
          even if you use replication filters to select different data
          to replicate on each channel. This is because the server IDs
          of replication slaves must be unique in a replication
          topology. The master distinguishes slaves only by their server
          IDs, not by the names of the replication channels, so it
          cannot recognize different replication channels from the same
          slave.
</p>
</div>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Important
</div>
<p>
          On a MySQL server instance that is configured for Group
          Replication, channel specific replication filters can be used
          on replication channels that are not directly involved with
          Group Replication, such as where a group member also acts as a
          replication slave to a master that is outside the group. They
          cannot be used on the
          <code class="literal">group_replication_applier</code> or
          <code class="literal">group_replication_recovery</code> channels.
          Filtering on these channels would make the group unable to
          reach agreement on a consistent state.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-rules-channel-overview"></a>Overview of Replication Filters and Channels</h5>

</div>

</div>

</div>
<p>
          When multiple replication channels exist, for example in a
          multi-source replication topology, replication filters are
          applied as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Any global replication filter specified is added to the
              global replication filters of the filter type
              (<code class="literal">do_db</code>,
              <code class="literal">do_ignore_table</code>, and so on).
            </p></li><li class="listitem"><p>
              Any channel specific replication filter adds the filter to
              the specified channel’s replication filters for the
              specified filter type.
            </p></li><li class="listitem"><p>
              Each slave replication channel copies global replication
              filters to its channel specific replication filters if no
              channel specific replication filter of this type is
              configured.
            </p></li><li class="listitem"><p>
              Each channel uses its channel specific replication filters
              to filter the replication stream.
</p></li></ul>
</div>
<p>
          The syntax to create channel specific replication filters
          extends the existing SQL statements and command options. When
          a replication channel is not specified the global replication
          filter is configured to ensure backwards compatibility. The
          <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION FILTER</code></a>
          statement supports the <code class="literal">FOR CHANNEL</code> clause
          to configure channel specific filters online. The
          <code class="literal">--replicate-*</code> command options to configure
          filters can specify a replication channel using the form
          <code class="literal">--replicate-<em class="replaceable"><code>filter_type</code></em>=<em class="replaceable"><code>channel_name</code></em>:<em class="replaceable"><code>filter_details</code></em></code>.
          For example, suppose channels <code class="literal">channel_1</code> and
          <code class="literal">channel_2</code> exist before the server starts,
          starting the slave with the command line options
          <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=db1</code></a>
          <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=channel_1:db2</code></a>
          <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db=db3</code></a>
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db=db4</code></a>
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db=channel_2:db5</code></a>
          would result in:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <span class="emphasis"><em>Global replication filters</em></span>:
              do_db=db1,db3, ignore_db=db4
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Channel specific filters on
              channel_1</em></span>: do_db=db2 ignore_db=db4
            </p></li><li class="listitem"><p>
              <span class="emphasis"><em>Channel specific filters on
              channel_2</em></span>: do_db=db1,db3 ignore_db=db5
</p></li></ul>
</div>
<p>
          To monitor the replication filters in such a setup use the
          <a class="link" href="performance-schema.html#replication-applier-global-filters-table" title="26.12.11.7 The replication_applier_global_filters Table"><code class="literal">replication_applier_global_filters</code></a>
          and <a class="link" href="performance-schema.html#replication-applier-filters-table" title="26.12.11.8 The replication_applier_filters Table"><code class="literal">replication_applier_filters</code></a>
          tables.

          
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-rules-channel-replication-filter-options"></a>Configuring Channel Specific Replication Filters at Startup</h5>

</div>

</div>

</div>
<p>
          The replication filter related command options can take an
          optional <em class="replaceable"><code>channel</code></em> followed by a
          colon, followed by the filter specification. The first colon
          is interpreted as a separator, subsequent colons are
          interpreted as literal colons. The following command options
          support channel specific replication filters using this
          format:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">--replicate-do-db=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>database_id</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-ignore-db=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>database_id</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-do-table=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>table_id</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-ignore-table=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>table_id</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-rewrite-db=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>db1-db2</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-wild-do-table=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>table
              regexid</code></em></code>
            </p></li><li class="listitem"><p>
              <code class="literal">--replicate-wild-ignore-table=<em class="replaceable"><code>channel</code></em>:<em class="replaceable"><code>table
              regexid</code></em></code>
</p></li></ul>
</div>
<p>
          If you use a colon but do not specify a
          <em class="replaceable"><code>channel</code></em> for the filter option, for
          example
          <code class="option">--replicate-do-db=:<em class="replaceable"><code>database_id</code></em></code>,
          the option configures the replication filter for the default
          replication channel. The default replication channel is the
          replication channel which always exists once replication has
          been started, and differs from multi-source replication
          channels which you create manually. When neither the colon nor
          a <em class="replaceable"><code>channel</code></em> is specified the option
          configures the global replication filters, for example
          <code class="option">--replicate-do-db=<em class="replaceable"><code>database_id</code></em></code>
          configures the global
          <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> filter.
        </p><p>
          If you configure multiple
          <code class="literal">rewrite-db=<em class="replaceable"><code>from_name</code></em>-&gt;<em class="replaceable"><code>to_name</code></em></code>
          options with the same <em class="replaceable"><code>from_name</code></em>
          database, all filters are added together (put into the
          <code class="literal">rewrite_do</code> list) and the first one takes
          effect.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-rules-channel-change-replication-filter"></a>Changing Channel Specific Replication Filters Online</h5>

</div>

</div>

</div>
<p>
          In addition to the <code class="option">--replicate-*</code> options,
          replication filters can be configured using the
          <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION FILTER</code></a>
          statement. This removes the need to restart the server, but
          the slave applier thread must be stopped while making the
          change. To make this statement apply the filter to a specific
          channel, use the <code class="literal">FOR CHANNEL
          <em class="replaceable"><code>channel</code></em></code> clause. For
          example:
        </p><pre data-lang="sql" class="programlisting">CHANGE REPLICATION FILTER REPLICATE_DO_DB=(db1) FOR CHANNEL channel_1;</pre><p>
          When a <code class="literal">FOR CHANNEL</code> clause is provided, the
          statement acts on the specified channel's replication
          filters. If multiple types of filters
          (<code class="literal">do_db</code>, <code class="literal">do_ignore_table</code>,
          <code class="literal">wild_do_table</code>, and so on) are specified,
          only the specified filter types are replaced by the statement.
          In a replication topology with multiple channels, for example
          on a multi-source replication slave, when no <code class="literal">FOR
          CHANNEL</code> clause is provided, the statement acts on
          the global replication filters and all channels’ replication
          filters, using a similar logic as the <code class="literal">FOR
          CHANNEL</code> case. For more information see
          <a class="xref" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement">Section 13.4.2.2, “CHANGE REPLICATION FILTER Statement”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="replication-rules-channel-removing"></a>Removing Channel Specific Replication Filters</h5>

</div>

</div>

</div>
<p>
          When channel specific replication filters have been
          configured, you can remove the filter by issuing an empty
          filter type statement. For example to remove all
          <code class="literal">REPLICATE_REWRITE_DB</code> filters from a
          replication channel named <code class="literal">channel_1</code> issue:
        </p><pre data-lang="sql" class="programlisting">CHANGE REPLICATION FILTER REPLICATE_REWRITE_DB=() FOR CHANNEL channel_1;</pre><p>
          Any <code class="literal">REPLICATE_REWRITE_DB</code> filters previously
          configured, using either command options or
          <a class="link" href="sql-statements.html#change-replication-filter" title="13.4.2.2 CHANGE REPLICATION FILTER Statement"><code class="literal">CHANGE REPLICATION FILTER</code></a>, are
          removed.
        </p><p>
          The <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE
          ALL</code></a> statement removes channel specific replication
          filters that were set on channels deleted by the statement.
          When the deleted channel or channels are recreated, any global
          replication filters specified for the slave are copied to
          them, and no channel specific replication filters are applied.
</p>
</div>

</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="replication-security"></a>17.3 Replication Security</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-solutions-encrypted-connections">17.3.1 Setting Up Replication to Use Encrypted Connections</a></span></dt><dt><span class="section"><a href="replication.html#replication-binlog-encryption">17.3.2 Encrypting Binary Log Files and Relay Log Files</a></span></dt><dt><span class="section"><a href="replication.html#replication-privilege-checks">17.3.3 Replication Privilege Checks</a></span></dt></dl>
</div>
<p>
    To protect against unauthorized access to data that is stored on and
    transferred between replication masters and slaves, set up all the
    servers involved using the security measures that you would choose
    for any MySQL instance in your installation, as described in
    <a class="xref" href="security.html" title="Chapter 6 Security">Chapter 6, <i>Security</i></a>. In addition, for servers in a
    replication topology, consider implementing the following security
    measures:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Set up masters and slaves to use encrypted connections to
        transfer the binary log, which protects this data in motion.
        Encryption for these connections must be activated using a
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement, in
        addition to setting up the servers to support encrypted network
        connections. See
        <a class="xref" href="replication.html#replication-solutions-encrypted-connections" title="17.3.1 Setting Up Replication to Use Encrypted Connections">Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”</a>.
      </p></li><li class="listitem"><p>
        Encrypt the binary log files and relay log files on masters and
        slaves, which protects this data at rest, and also any data in
        use in the binary log cache. Binary log encryption is activated
        using the <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a>
        system variable. See
        <a class="xref" href="replication.html#replication-binlog-encryption" title="17.3.2 Encrypting Binary Log Files and Relay Log Files">Section 17.3.2, “Encrypting Binary Log Files and Relay Log Files”</a>.
      </p></li><li class="listitem"><p>
        Apply privilege checks to replication appliers, which help to
        secure replication channels against the unauthorized or
        accidental use of privileged or unwanted operations. Privilege
        checks are implemented by setting up a
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account, which MySQL
        uses to verify that you have authorized each specific
        transaction for that channel. See
        <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>.
</p></li></ul>
</div>
<p>
    For Group Replication, binary log encryption and privilege checks
    can be used as a security measure on replication group members. You
    should also consider encrypting the connections between group
    members, comprising group communication connections and distributed
    recovery connections, and applying IP address whitelisting to
    exclude untrusted hosts. For information on these security measures
    specific to Group Replication, see
    <a class="xref" href="group-replication.html#group-replication-security" title="18.5 Group Replication Security">Section 18.5, “Group Replication Security”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-encrypted-connections"></a>17.3.1 Setting Up Replication to Use Encrypted Connections</h3>
</div>
</div>
</div>
<p>
      To use an encrypted connection for the transfer of the binary log
      required during replication, both the master and the slave servers
      must support encrypted network connections. If either server does
      not support encrypted connections (because it has not been
      compiled or configured for them), replication through an encrypted
      connection is not possible.
    </p><p>
      Setting up encrypted connections for replication is similar to
      doing so for client/server connections. You must obtain (or
      create) a suitable security certificate that you can use on the
      master, and a similar certificate (from the same certificate
      authority) on each slave. You must also obtain suitable key files.
    </p><p>
      For more information on setting up a server and client for
      encrypted connections, see
      <a class="xref" href="security.html#using-encrypted-connections" title="6.3.1 Configuring MySQL to Use Encrypted Connections">Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”</a>.
    </p><p>
      To enable encrypted connections on the master, you must create or
      obtain suitable certificate and key files, and then add the
      following configuration parameters to the master's configuration
      within the <code class="literal">[mysqld]</code> section of the master's
      <code class="filename">my.cnf</code> file, changing the file names as
      necessary:
    </p><pre data-lang="ini" class="programlisting">[mysqld]
ssl_ca=cacert.pem
ssl_cert=server-cert.pem
ssl_key=server-key.pem</pre><p>
      The paths to the files may be relative or absolute; we recommend
      that you always use complete paths for this purpose.
    </p><p>
      The configuration parameters are as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <a class="link" href="server-administration.html#sysvar_ssl_ca"><code class="literal">ssl_ca</code></a>: The path name of the
          Certificate Authority (CA) certificate file.
          (<a class="link" href="server-administration.html#sysvar_ssl_capath"><code class="literal">ssl_capath</code></a> is similar but
          specifies the path name of a directory of CA certificate
          files.)
        </p></li><li class="listitem"><p>
          <a class="link" href="server-administration.html#sysvar_ssl_cert"><code class="literal">ssl_cert</code></a>: The path name of
          the server public key certificate file. This certificate can
          be sent to the client and authenticated against the CA
          certificate that it has.
        </p></li><li class="listitem"><p>
          <a class="link" href="server-administration.html#sysvar_ssl_key"><code class="literal">ssl_key</code></a>: The path name of the
          server private key file.
</p></li></ul>
</div>
<p>
      To enable encrypted connections on the slave, use the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement. You can
      either name the slave certificate and SSL private key files
      required for the encrypted connection in the
      <code class="literal">[client]</code> section of the slave's
      <code class="filename">my.cnf</code> file, or you can explicitly specify
      that information using the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement. For more information on the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement, see
      <a class="xref" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement">Section 13.4.2.1, “CHANGE MASTER TO Statement”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To name the slave certificate and key files using an option
          file, add the following lines to the
          <code class="literal">[client]</code> section of the slave's
          <code class="filename">my.cnf</code> file, changing the file names as
          necessary:
        </p><pre data-lang="ini" class="programlisting">[client]
ssl-ca=cacert.pem
ssl-cert=client-cert.pem
ssl-key=client-key.pem</pre></li><li class="listitem"><p>
          Restart the slave server, using the
          <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option to
          prevent the slave from connecting to the master. Use
          <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> to specify the
          master configuration, and add the
          <code class="literal">MASTER_SSL</code> option to connect using
          encryption:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_HOST='master_hostname',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_USER='repl',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_PASSWORD='<em class="replaceable"><code>password</code></em>',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_SSL=1;</code></strong>
</pre><p>
          Setting <code class="literal">MASTER_SSL=1</code> for a replication
          connection and then setting no further
          <code class="literal">MASTER_SSL_<em class="replaceable"><code>xxx</code></em></code>
          options corresponds to setting
          <code class="literal">--ssl-mode=REQUIRED</code> for the client, as
          described in <a class="xref" href="programs.html#encrypted-connection-options" title="Command Options for Encrypted Connections">Command Options for Encrypted Connections</a>.
          With <code class="literal">MASTER_SSL=1</code>, the connection attempt
          only succeeds if an encrypted connection can be established. A
          replication connection does not fall back to an unencrypted
          connection, so there is no setting corresponding to the
          <code class="literal">--ssl-mode=PREFERRED</code> setting for
          replication. If <code class="literal">MASTER_SSL=0</code> is set, this
          corresponds to <code class="literal">--ssl-mode=DISABLED</code>.
        </p></li><li class="listitem"><p>
          To name the slave certificate and SSL private key files using
          the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement,
          if you did not do this in the slave's
          <code class="filename">my.cnf</code> file, add the appropriate
          <code class="literal">MASTER_SSL_<em class="replaceable"><code>xxx</code></em></code>
          options:
        </p><pre data-lang="sql" class="programlisting">    -&gt; <strong class="userinput"><code>MASTER_SSL_CA = 'ca_file_name',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_SSL_CAPATH = 'ca_directory_name',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_SSL_CERT = 'cert_file_name',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_SSL_KEY = 'key_file_name',</code></strong>
</pre><p>
          These options correspond to the
          <code class="literal">--ssl-<em class="replaceable"><code>xxx</code></em></code>
          options with the same names, as described in
          <a class="xref" href="programs.html#encrypted-connection-options" title="Command Options for Encrypted Connections">Command Options for Encrypted Connections</a>. For these
          options to take effect, <code class="literal">MASTER_SSL=1</code> must
          also be set. For a replication connection, specifying a value
          for either of <code class="literal"> MASTER_SSL_CA</code> or
          <code class="literal">MASTER_SSL_CAPATH</code>, or specifying these
          options in the slave's <code class="filename">my.cnf</code> file,
          corresponds to setting
          <code class="literal">--ssl-mode=VERIFY_CA</code>. The connection
          attempt only succeeds if a valid matching Certificate
          Authority (CA) certificate is found using the specified
          information.
        </p></li><li class="listitem"><p>
          To activate host name identity verification, add the
          <code class="literal">MASTER_SSL_VERIFY_SERVER_CERT</code> option:
        </p><pre data-lang="sql" class="programlisting">    -&gt; <strong class="userinput"><code>MASTER_SSL_VERIFY_SERVER_CERT=1,</code></strong>
</pre><p>
          This option corresponds to the
          <code class="literal">--ssl-verify-server-cert</code> option, which was
          deprecated from MySQL 5.7 and removed in MySQL 8.0. For a
          replication connection, specifying
          <code class="literal">MASTER_SSL_VERIFY_SERVER_CERT=1</code> corresponds
          to setting <code class="literal">--ssl-mode=VERIFY_IDENTITY</code>, as
          described in <a class="xref" href="programs.html#encrypted-connection-options" title="Command Options for Encrypted Connections">Command Options for Encrypted Connections</a>.
          For this option to take effect,
          <code class="literal">MASTER_SSL=1</code> must also be set. Host name
          identity verification does not work with self-signed
          certificates.
        </p></li><li class="listitem"><p>
          To activate certificate revocation list (CRL) checks, add the
          <code class="literal">MASTER_SSL_CRL</code> or
          <code class="literal">MASTER_SSL_CRLPATH</code> option:
        </p><pre data-lang="sql" class="programlisting">    -&gt; <strong class="userinput"><code>MASTER_SSL_CRL = 'crl_file_name',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_SSL_CRLPATH = 'crl_directory_name',</code></strong></pre><p>
          These options correspond to the
          <code class="literal">--ssl-<em class="replaceable"><code>xxx</code></em></code>
          options with the same names, as described in
          <a class="xref" href="programs.html#encrypted-connection-options" title="Command Options for Encrypted Connections">Command Options for Encrypted Connections</a>. If they are
          not specified, no CRL checking takes place.
        </p></li><li class="listitem"><p>
          To specify lists of ciphers, ciphersuites, and encryption
          protocols permitted by the slave for the replication
          connection, use the <code class="literal">MASTER_SSL_CIPHER</code>,
          <code class="literal">MASTER_TLS_VERSION</code>, and
          <code class="literal">MASTER_TLS_CIPHERSUITES</code> options:
        </p><pre data-lang="sql" class="programlisting">    -&gt; <strong class="userinput"><code>MASTER_SSL_CIPHER = 'cipher_list',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_TLS_VERSION = 'protocol_list',</code></strong>
    -&gt; <strong class="userinput"><code>MASTER_TLS_CIPHERSUITES = 'ciphersuite_list',</code></strong>
</pre>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              The <code class="literal">MASTER_SSL_CIPHER</code> option specifies
              a colon-separated list of one or more ciphers permitted by
              the slave for the replication connection.
            </p></li><li class="listitem"><p>
              The <code class="literal">MASTER_TLS_VERSION</code> option specifies
              a comma-separated list of the TLS encryption protocols
              permitted by the slave for the replication connection, in
              a format like that for the
              <a class="link" href="server-administration.html#sysvar_tls_version"><code class="literal">tls_version</code></a> server system
              variable. The connection procedure negotiates the use of
              the highest TLS version that both the master and the slave
              permit. To be able to connect, the slave must have at
              least one TLS version in common with the master.
            </p></li><li class="listitem"><p>
              The <code class="literal">MASTER_TLS_CIPHERSUITES</code> option
              (available from MySQL 8.0.19) specifies a colon-separated
              list of one or more ciphersuites that are permitted by the
              slave for the replication connection if TLSv1.3 is used
              for the connection. If this option is set to
              <code class="literal">NULL</code> when TLSv1.3 is used (which is the
              default if you do not set the option), the ciphersuites
              that are enabled by default are allowed. If you set the
              option to an empty string, no ciphersuites are allowed,
              and TLSv1.3 will therefore not be used.
</p></li></ul>
</div>
<p>
          The protocols, ciphers, and ciphersuites that you can specify
          in these lists depend on the SSL library used to compile
          MySQL. For information about the formats, the permitted
          values, and the defaults if you do not specify the options,
          see <a class="xref" href="security.html#encrypted-connection-protocols-ciphers" title="6.3.2 Encrypted Connection TLS Protocols and Ciphers">Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            In MySQL 8.0.16 through 8.0.18, MySQL supports TLSv1.3, but
            the <code class="literal">MASTER_TLS_CIPHERSUITES</code> option is not
            available. In these releases, if TLSv1.3 is used for
            connections between a replication master and slave, the
            replication master must permit the use of at least one
            TLSv1.3 ciphersuite that is enabled by default. From MySQL
            8.0.19, you can use the option to specify any selection of
            ciphersuites, including only non-default ciphersuites if you
            want.
</p>
</div>
</li><li class="listitem"><p>
          After the master information has been updated, start the slave
          replication process:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre><p>
          You can use the <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
          STATUS</code></a> statement to confirm that an encrypted
          connection was established successfully.
        </p></li><li class="listitem"><p>
          Requiring encrypted connections on the slave does not ensure
          that the master requires encrypted connections from slaves. If
          you want to ensure that the master only accepts replication
          slaves that connect using encrypted connections, create a
          replication user account on the master using the
          <code class="literal">REQUIRE SSL</code> option, then grant that user
          the <a class="link" href="security.html#priv_replication-slave"><code class="literal">REPLICATION SLAVE</code></a>
          privilege. For example:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CREATE USER 'repl'@'%.example.com' IDENTIFIED BY '<em class="replaceable"><code>password</code></em>'</code></strong>
    -&gt; <strong class="userinput"><code>REQUIRE SSL;</code></strong>
mysql&gt; <strong class="userinput"><code>GRANT REPLICATION SLAVE ON *.*</code></strong>
    -&gt; <strong class="userinput"><code>TO 'repl'@'%.example.com';</code></strong>
</pre><p>
          If you have an existing replication user account on the
          master, you can add <code class="literal">REQUIRE SSL</code> to it with
          this statement:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>ALTER USER 'repl'@'%.example.com' REQUIRE SSL;</code></strong>
</pre></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-binlog-encryption"></a>17.3.2 Encrypting Binary Log Files and Relay Log Files</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-binlog-encryption-scope">17.3.2.1 Scope of Binary Log Encryption</a></span></dt><dt><span class="section"><a href="replication.html#replication-binlog-encryption-encryption-keys">17.3.2.2 Binary Log Encryption Keys</a></span></dt><dt><span class="section"><a href="replication.html#replication-binlog-encryption-key-rotation">17.3.2.3 Binary Log Master Key Rotation</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444262791680"></a><a class="indexterm" name="idm46444262790608"></a><p>
      From MySQL 8.0.14, binary log files and relay log files can be
      encrypted, helping to protect these files and the potentially
      sensitive data contained in them from being misused by outside
      attackers, and also from unauthorized viewing by users of the
      operating system where they are stored. The encryption algorithm
      used for the files, the AES (Advanced Encryption Standard) cipher
      algorithm, is built in to MySQL Server and cannot be configured.
    </p><p>
      You enable this encryption on a MySQL server by setting the
      <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a> system variable
      to <code class="literal">ON</code>. <code class="literal">OFF</code> is the default.
      The system variable sets encryption on for binary log files and
      relay log files. Binary logging does not need to be enabled on the
      server to enable encryption, so you can encrypt the relay log
      files on a slave that has no binary log. To use encryption, a
      keyring plugin must be installed and configured to supply MySQL
      Server's keyring service. For instructions to do this, see
      <a class="xref" href="security.html#keyring" title="6.4.4 The MySQL Keyring">Section 6.4.4, “The MySQL Keyring”</a>. Any supported keyring plugin can be
      used to store binary log encryption keys.
    </p><p>
      When you first start the server with encryption enabled, a new
      binary log encryption key is generated before the binary log and
      relay logs are initialized. This key is used to encrypt a file
      password for each binary log file (if the server has binary
      logging enabled) and relay log file (if the server has replication
      channels), and further keys generated from the file passwords are
      used to encrypt the data in the files. The binary log encryption
      key that is currently in use on the server is called the binary
      log master key. The two tier encryption key architecture means
      that the binary log master key can be rotated (replaced by a new
      master key) as required, and only the file password for each file
      needs to be re-encrypted with the new master key, not the whole
      file. Relay log files are encrypted for all channels, including
      new channels that are created after encryption is activated. The
      binary log index file and relay log index file are never
      encrypted.
    </p><p>
      If you activate encryption while the server is running, a new
      binary log encryption key is generated at that time. The exception
      is if encryption was active previously on the server and was then
      disabled, in which case the binary log encryption key that was in
      use before is used again. The binary log file and relay log files
      are rotated immediately, and file passwords for the new files and
      all subsequent binary log files and relay log files are encrypted
      using this binary log encryption key. Existing binary log files
      and relay log files still present on the server are not encrypted,
      but you can purge them if they are no longer needed.
    </p><p>
      If you deactivate encryption by changing the
      <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a> system variable
      to <code class="literal">OFF</code>, the binary log file and relay log files
      are rotated immediately and all subsequent logging is unencrypted.
      Previously encrypted files are not automatically decrypted, but
      the server is still able to read them. The
      <a class="link" href="security.html#priv_binlog-encryption-admin"><code class="literal">BINLOG_ENCRYPTION_ADMIN</code></a> privilege
      is required to activate or deactivate encryption while the server
      is running.
    </p><p>
      Encrypted and unencrypted binary log files can be distinguished
      using the magic number at the start of the file header for
      encrypted log files (<code class="literal">0xFD62696E</code>), which differs
      from that used for unencrypted log files
      (<code class="literal">0xFE62696E</code>). The <a class="link" href="sql-statements.html#show-binary-logs" title="13.7.7.1 SHOW BINARY LOGS Statement"><code class="literal">SHOW
      BINARY LOGS</code></a> statement shows whether each binary log file
      is encrypted or unencrypted.
    </p><p>
      When binary log files have been encrypted,
      <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> cannot read them directly, but can
      read them from the server using the
      <a class="link" href="programs.html#option_mysqlbinlog_read-from-remote-server"><code class="option">--read-from-remote-server</code></a>
      option. From MySQL 8.0.14, <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> returns
      a suitable error if you attempt to read an encrypted binary log
      file directly, but older versions of
      <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> do not recognise the file as a
      binary log file at all. If you back up encrypted binary log files
      using <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, note that the copies of the
      files that are generated using <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> are
      stored in an unencrypted format.
    </p><p>
      Binary log encryption can be combined with binary log transaction
      compression (available as of MySQL 8.0.20). For more information
      on binary log transaction compression, see
      <a class="xref" href="server-administration.html#binary-log-transaction-compression" title="5.4.4.5 Binary Log Transaction Compression">Section 5.4.4.5, “Binary Log Transaction Compression”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-binlog-encryption-scope"></a>17.3.2.1 Scope of Binary Log Encryption</h4>
</div>
</div>
</div>
<p>
        When binary log encryption is active for a MySQL server
        instance, the encryption coverage is as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Data at rest that is written to the binary log files and
            relay log files is encrypted from the point in time where
            encryption is started, using the two tier encryption
            architecture described above. Existing binary log files and
            relay log files that were present on the server when you
            started encryption are not encrypted. You can purge these
            files when they are no longer needed.
          </p></li><li class="listitem"><p>
            Data in motion in the replication event stream, which is
            sent to MySQL clients including
            <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, is decrypted for
            transmission, and should therefore be protected in transit
            by the use of connection encryption (see
            <a class="xref" href="security.html#encrypted-connections" title="6.3 Using Encrypted Connections">Section 6.3, “Using Encrypted Connections”</a> and
            <a class="xref" href="replication.html#replication-solutions-encrypted-connections" title="17.3.1 Setting Up Replication to Use Encrypted Connections">Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”</a>).
          </p></li><li class="listitem"><p>
            Data in use that is held in the binary log transaction and
            statement caches during a transaction is in unencrypted
            format in the memory buffer that stores the cache. The data
            is written to a temporary file on disk if it exceeds the
            space available in the memory buffer. From MySQL 8.0.17,
            when binary log encryption is active on the server,
            temporary files used to hold the binary log cache are
            encrypted using AES-CTR (AES Counter mode) for stream
            encryption. Because the temporary files are volatile and
            tied to a single process, they are encrypted using
            single-tier encryption, using a randomly generated file
            password and initialization vector that exist only in memory
            and are never stored on disk or in the keyring. After each
            transaction is committed, the binary log cache is reset: the
            memory buffer is cleared, any temporary file used to hold
            the binary log cache is truncated, and a new file password
            and initialization vector are randomly generated for use
            with the next transaction. This reset also takes place when
            the server is restarted after a normal shutdown or an
            unexpected halt.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          If you use <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> when
          <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a> is
          set, which is not recommended as the statement is considered
          unsafe for statement-based replication, a temporary file
          containing the data is created on the replication slave where
          the changes are applied. These temporary files are not
          encrypted when binary log encryption is active on the server.
          Use row-based or mixed binary logging format instead, which do
          not create the temporary files.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-binlog-encryption-encryption-keys"></a>17.3.2.2 Binary Log Encryption Keys</h4>

</div>

</div>

</div>
<p>
        The binary log encryption keys used to encrypt the file
        passwords for the log files are 256-bit keys that are generated
        specifically for each MySQL server instance using MySQL Server's
        keyring service (see <a class="xref" href="security.html#keyring" title="6.4.4 The MySQL Keyring">Section 6.4.4, “The MySQL Keyring”</a>). The keyring
        service handles the creation, retrieval, and deletion of the
        binary log encryption keys. A server instance only creates and
        removes keys generated for itself, but it can read keys
        generated for other instances if they are stored in the keyring,
        as in the case of a server instance that has been cloned by file
        copying.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          The binary log encryption keys for a MySQL server instance
          must be included in your backup and recovery procedures,
          because if the keys required to decrypt the file passwords for
          current and retained binary log files or relay log files are
          lost, it might not be possible to start the server.
</p>
</div>
<p>
        The format of binary log encryption keys in the keyring is as
        follows:
      </p><pre data-lang="simple" class="programlisting">MySQLReplicationKey_{UUID}_{SEQ_NO}</pre><p>
        For example:
      </p><pre data-lang="simple" class="programlisting">MySQLReplicationKey_00508583-b5ce-11e8-a6a5-0010e0734796_1 </pre><p>
        <code class="literal">{UUID}</code> is the true UUID generated by the
        MySQL server (the value of the
        <a class="link" href="replication.html#sysvar_server_uuid"><code class="literal">server_uuid</code></a> system variable).
        <code class="literal">{SEQ_NO}</code> is the sequence number for the
        binary log encryption key, which is incremented by 1 for each
        new key that is generated on the server.
      </p><p>
        The binary log encryption key that is currently in use on the
        server is called the binary log master key. The sequence number
        for the current binary log master key is stored in the keyring.
        The binary log master key is used to encrypt each new log file's
        file password, which is a randomly generated 32-byte file
        password specific to the log file that is used to encrypt the
        file data. The file password is encrypted using AES-CBC (AES
        Cipher Block Chaining mode) with the 256-bit binary log
        encryption key and a random initialization vector (IV), and is
        stored in the log file's file header. The file data is encrypted
        using AES-CTR (AES Counter mode) with a 256-bit key generated
        from the file password and a nonce also generated from the file
        password. It is technically possible to decrypt an encrypted
        file offline, if the binary log encryption key used to encrypt
        the file password is known, by using tools available in the
        OpenSSL cryptography toolkit.
      </p><p>
        If you use file copying to clone a MySQL server instance that
        has encryption active so its binary log files and relay log
        files are encrypted, ensure that the keyring is also copied, so
        that the clone server can read the binary log encryption keys
        from the source server. When encryption is activated on the
        clone server (either at startup or subsequently), the clone
        server recognizes that the binary log encryption keys used with
        the copied files include the generated UUID of the source
        server. It automatically generates a new binary log encryption
        key using its own generated UUID, and uses this to encrypt the
        file passwords for subsequent binary log files and relay log
        files. The copied files continue to be read using the source
        server's keys.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-binlog-encryption-key-rotation"></a>17.3.2.3 Binary Log Master Key Rotation</h4>

</div>

</div>

</div>
<p>
        When binary log encryption is enabled, you can rotate the binary
        log master key at any time while the server is running by
        issuing <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG MASTER
        KEY</code></a>. When the binary log master key is rotated
        manually using this statement, the passwords for the new and
        subsequent files are encrypted using the new binary log master
        key, and also the file passwords for existing encrypted binary
        log files and relay log files are re-encrypted using the new
        binary log master key, so the encryption is renewed completely.
        You can rotate the binary log master key on a regular basis to
        comply with your organization's security policy, and also if you
        suspect that the current or any of the previous binary log
        master keys might have been compromised.
      </p><p>
        When you rotate the binary log master key manually, MySQL Server
        takes the following actions in sequence:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            A new binary log encryption key is generated with the next
            available sequence number, stored on the keyring, and used
            as the new binary log master key.
          </p></li><li class="listitem"><p>
            The binary log and relay log files are rotated on all
            channels.
          </p></li><li class="listitem"><p>
            The new binary log master key is used to encrypt the file
            passwords for the new binary log and relay log files, and
            subsequent files until the key is changed again.
          </p></li><li class="listitem"><p>
            The file passwords for existing encrypted binary log files
            and relay log files on the server are re-encrypted in turn
            using the new binary log master key, starting with the most
            recent files. Any unencrypted files are skipped.
          </p></li><li class="listitem"><p>
            Binary log encryption keys that are no longer in use for any
            files after the re-encryption process are removed from the
            keyring.
</p></li></ol>
</div>
<p>
        The <a class="link" href="security.html#priv_binlog-encryption-admin"><code class="literal">BINLOG_ENCRYPTION_ADMIN</code></a>
        privilege is required to issue <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER
        INSTANCE ROTATE BINLOG MASTER KEY</code></a>, and the statement
        cannot be used if the
        <a class="link" href="replication.html#sysvar_binlog_encryption"><code class="literal">binlog_encryption</code></a> system
        variable is set to <code class="literal">OFF</code>.
      </p><p>
        As the final step of the binary log master key rotation process,
        all binary log encryption keys that no longer apply to any
        retained binary log files or relay log files are cleaned up from
        the keyring. If a retained binary log file or relay log file
        cannot be initialized for re-encryption, the relevant binary log
        encryption keys are not deleted in case the files can be
        recovered in the future. For example, this might be the case if
        a file listed in a binary log index file is currently
        unreadable, or if a channel fails to initialize. If the server
        UUID changes, for example because a backup created using MySQL
        Enterprise Backup is used to set up a new replication slave,
        issuing <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG MASTER
        KEY</code></a> on the new server does not delete any earlier
        binary log encryption keys that include the original server
        UUID.
      </p><p>
        If any of the first four steps of the binary log master key
        rotation process cannot be completed correctly, an error message
        is issued explaining the situation and the consequences for the
        encryption status of the binary log files and relay log files.
        Files that were previously encrypted are always left in an
        encrypted state, but their file passwords might still be
        encrypted using an old binary log master key. If you see these
        errors, first retry the process by issuing
        <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG MASTER
        KEY</code></a> again. Then investigate the status of individual
        files to see what is blocking the process, especially if you
        suspect that the current or any of the previous binary log
        master keys might have been compromised.
      </p><p>
        If the final step of the binary log master key rotation process
        cannot be completed correctly, a warning message is issued
        explaining the situation. The warning message identifies whether
        the process could not clean up the auxiliary keys in the keyring
        for rotating the binary log master key, or could not clean up
        unused binary log encryption keys. You can choose to ignore the
        message as the keys are auxiliary keys or no longer in use, or
        you can issue <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG
        MASTER KEY</code></a> again to retry the process.
      </p><p>
        If the server stops and is restarted with binary log encryption
        still set to <code class="literal">ON</code> during the binary log master
        key rotation process, new binary log files and relay log files
        after the restart are encrypted using the new binary log master
        key. However, the re-encryption of existing files is not
        continued, so files that did not get re-encrypted before the
        server stopped are left encrypted using the previous binary log
        master key. To complete re-encryption and clean up unused binary
        log encryption keys, issue <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE
        ROTATE BINLOG MASTER KEY</code></a> again after the restart.
      </p><p>
        <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG MASTER
        KEY</code></a> actions are not written to the binary log and are
        not executed on replication slaves. Binary log master key
        rotation can therefore be carried out in replication
        environments including a mix of MySQL versions. To schedule
        regular rotation of the binary log master key on all applicable
        master and slave servers, you can enable the MySQL Event
        Scheduler on each server and issue the
        <a class="link" href="sql-statements.html#alter-instance-rotate-binlog-master-key"><code class="literal">ALTER INSTANCE ROTATE BINLOG MASTER
        KEY</code></a> statement using a <a class="link" href="sql-statements.html#create-event" title="13.1.13 CREATE EVENT Statement"><code class="literal">CREATE
        EVENT</code></a> statement. If you rotate the binary log master
        key because you suspect that the current or any of the previous
        binary log master keys might have been compromised, issue the
        statement on every applicable master and slave server. Issuing
        the statement on individual servers ensures that you can verify
        immediate compliance, even in the case of slaves that are
        lagging, belong to multiple replication topologies, or are not
        currently active in the replication topology but have binary log
        and relay log files.
      </p><p>
        The
        <a class="link" href="replication.html#sysvar_binlog_rotate_encryption_master_key_at_startup"><code class="literal">binlog_rotate_encryption_master_key_at_startup</code></a>
        system variable controls whether the binary log master key is
        automatically rotated when the server is restarted. If this
        system variable is set to <code class="literal">ON</code>, a new binary
        log encryption key is generated and used as the new binary log
        master key whenever the server is restarted. If it is set to
        <code class="literal">OFF</code>, which is the default, the existing
        binary log master key is used again after the restart. When the
        binary log master key is rotated at startup, the file passwords
        for the new binary log and relay log files are encrypted using
        the new key. The file passwords for the existing encrypted
        binary log files and relay log files are not re-encrypted, so
        they remain encrypted using the old key, which remains available
        on the keyring.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-privilege-checks"></a>17.3.3 Replication Privilege Checks</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-privilege-checks-account">17.3.3.1 Privileges For The Replication PRIVILEGE_CHECKS_USER Account</a></span></dt><dt><span class="section"><a href="replication.html#replication-privilege-checks-gr">17.3.3.2 Privilege Checks For Group Replication Channels</a></span></dt><dt><span class="section"><a href="replication.html#replication-privilege-checks-recover">17.3.3.3 Recovering From Failed Replication Privilege Checks</a></span></dt></dl>
</div>
<p>
      By default, MySQL replication (including Group Replication) does
      not carry out privilege checks when transactions that were already
      accepted by another server are applied on a replication slave or
      group member. From MySQL 8.0.18, you can create a user account
      with the appropriate privileges to apply the transactions that are
      normally replicated on a channel, and specify this as the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account for the
      replication applier, using a <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement. MySQL then checks each transaction against
      the user account's privileges to verify that you have authorized
      the operation for that channel. The account can also be safely
      used by an administrator to apply or reapply transactions from
      <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output, for example to recover from
      a replication error on the channel.
    </p><p>
      The use of a <code class="literal">PRIVILEGE_CHECKS_USER</code> account
      helps secure a replication channel against the unauthorized or
      accidental use of privileged or unwanted operations. The
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account provides an
      additional layer of security in situations such as these:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          You are replicating between a server instance on your
          organization's network, and a server instance on another
          network, such as an instance supplied by a cloud service
          provider.
        </p></li><li class="listitem"><p>
          You want to have multiple on-premise or off-site deployments
          administered as separate units, without giving one
          administrator account privileges on all the deployments.
        </p></li><li class="listitem"><p>
          You want to have an administrator account that enables an
          administrator to perform only operations that are directly
          relevant to the replication channel and the databases it
          replicates, rather than having wide privileges on the server
          instance.
</p></li></ul>
</div>
<p>
      You can increase the security of a replication channel where
      privilege checks are applied by adding one or both of these
      options to the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
      statement when you specify the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account for the channel:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The <code class="literal">REQUIRE_ROW_FORMAT</code> option (available
          from MySQL 8.0.19) makes the replication channel accept only
          row-based replication events. When
          <code class="literal">REQUIRE_ROW_FORMAT</code> is set, you must use
          row-based binary logging
          (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>) on the
          master. In MySQL 8.0.18, <code class="literal">REQUIRE_ROW_FORMAT</code>
          is not available, but the use of row-based binary logging for
          secured replication channels is still strongly recommended.
          With statement-based binary logging, some administrator-level
          privileges might be required for the
          <code class="literal">PRIVILEGE_CHECKS_USER</code> account to execute
          transactions successfully.
        </p></li><li class="listitem"><p>
          The <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> option
          (available from MySQL 8.0.20) makes the replication channel
          use its own policy for primary key checks. Setting
          <code class="literal">ON</code> means that primary keys are always
          required, and setting <code class="literal">OFF</code> means that
          primary keys are never required. The default setting,
          <code class="literal">STREAM</code>, sets the session value of the
          <a class="link" href="server-administration.html#sysvar_sql_require_primary_key"><code class="literal">sql_require_primary_key</code></a>
          system variable using the value that is replicated from the
          master for each transaction. When
          <code class="literal">PRIVILEGE_CHECKS_USER</code> is set, setting
          <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> to either
          <code class="literal">ON</code> or <code class="literal">OFF</code> means that the
          user account does not need session administration level
          privileges to set restricted session variables, which are
          required to change the value of
          <a class="link" href="server-administration.html#sysvar_sql_require_primary_key"><code class="literal">sql_require_primary_key</code></a>. It
          also normalizes the behavior across replication channels for
          different masters.
</p></li></ul>
</div>
<p>
      You grant the <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a>
      privilege to enable a user account to appear as the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> for a replication applier
      thread, and to execute the internal-use
      <a class="link" href="sql-statements.html#binlog" title="13.7.8.1 BINLOG Statement"><code class="literal">BINLOG</code></a> statements used by
      mysqlbinlog. The user name and host name for the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account must follow the
      syntax described in <a class="xref" href="security.html#account-names" title="6.2.4 Specifying Account Names">Section 6.2.4, “Specifying Account Names”</a>, and the user
      must not be an anonymous user (with a blank user name) or the
      <code class="literal">CURRENT_USER</code>. To create a new account, use
      <a class="link" href="sql-statements.html#create-user" title="13.7.1.3 CREATE USER Statement"><code class="literal">CREATE USER</code></a>. To grant this account
      the <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege,
      use the <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a> statement. For
      example, to create a user account <code class="literal">priv_repl</code>,
      which can be used manually by an administrator from any host in
      the <code class="literal">example.com</code> domain, and requires an
      encrypted connection, issue the following statements:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; SET sql_log_bin = 0;
mysql&gt; CREATE USER 'priv_repl'@'%.example.com' IDENTIFIED BY '<em class="replaceable"><code>password</code></em>' REQUIRE SSL;
mysql&gt; GRANT REPLICATION_APPLIER ON *.* TO 'priv_repl'@'%.example.com';
mysql&gt; SET sql_log_bin = 1;
</pre><p>
      The <code class="literal">SET sql_log_bin</code> statements are used so that
      the account management statements are not added to the binary log
      and sent to the replication channels (see
      <a class="xref" href="sql-statements.html#set-sql-log-bin" title="13.4.1.3 SET sql_log_bin Statement">Section 13.4.1.3, “SET sql_log_bin Statement”</a>).
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        The <code class="literal">caching_sha2_password</code> authentication
        plugin is the default for new users created from MySQL 8.0 (for
        details, see
        <a class="xref" href="security.html#caching-sha2-pluggable-authentication" title="6.4.1.2 Caching SHA-2 Pluggable Authentication">Section 6.4.1.2, “Caching SHA-2 Pluggable Authentication”</a>). To
        connect to a server using a user account that authenticates with
        this plugin, you must either set up an encrypted connection as
        described in
        <a class="xref" href="replication.html#replication-solutions-encrypted-connections" title="17.3.1 Setting Up Replication to Use Encrypted Connections">Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”</a>,
        or enable the unencrypted connection to support password
        exchange using an RSA key pair.
</p>
</div>
<p>
      After setting up the user account, use the
      <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a> statement to grant additional
      privileges to enable the user account to make the database changes
      that you expect the applier thread to carry out, such as updating
      specific tables held on the server. These same privileges enable
      an administrator to use the account if they need to execute any of
      those transactions manually on the replication channel. If an
      unexpected operation is attempted for which you did not grant the
      appropriate privileges, the operation is disallowed and the
      replication applier thread stops with an error.
      <a class="xref" href="replication.html#replication-privilege-checks-account" title="17.3.3.1 Privileges For The Replication PRIVILEGE_CHECKS_USER Account">Section 17.3.3.1, “Privileges For The Replication PRIVILEGE_CHECKS_USER Account”</a> explains
      what additional privileges the account needs. For example, to
      grant the <code class="literal">priv_repl</code> user account the
      <a class="link" href="security.html#priv_insert"><code class="literal">INSERT</code></a> privilege to add rows to the
      <code class="literal">cust</code> table in <code class="literal">db1</code>, issue the
      following statement:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; GRANT INSERT ON db1.cust TO 'priv_repl'@'%.example.com';</pre><p>
      You assign the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
      for a replication channel using a <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE
      MASTER TO</code></a> statement. The use of row-based binary logging
      is strongly recommended when
      <code class="literal">PRIVILEGE_CHECKS_USER</code> is set, and from MySQL
      8.0.19 you can use the statement to set
      <code class="literal">REQUIRE_ROW_FORMAT</code> to enforce this. If
      replication is running, issue <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP
      SLAVE</code></a> before the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
      TO</code></a> statement, and <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
      SLAVE</code></a> after it. For example, to start privilege checks
      on the channel <code class="literal">channel_1</code> on a running
      replication slave, issue the following statements:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; STOP SLAVE FOR CHANNEL 'channel_1';
mysql&gt; CHANGE MASTER TO 
         PRIVILEGE_CHECKS_USER = 'priv_repl'@'%.example.com',
         REQUIRE_ROW_FORMAT = 1 FOR CHANNEL 'channel_1'; 
mysql&gt; START SLAVE FOR CHANNEL 'channel_1';</pre><p>
      When you restart the replication channel, the privilege checks are
      applied from that point on. If you do not specify a channel and no
      other channels exist, the statement is applied to the default
      channel. The user name and host name for the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account for a channel are
      shown in the Performance Schema
      <a class="link" href="performance-schema.html#replication-applier-configuration-table" title="26.12.11.3 The replication_applier_configuration Table"><code class="literal">replication_applier_configuration</code></a>
      table, where they are properly escaped so they can be copied
      directly into SQL statements to execute individual transactions.
    </p><p>
      When <code class="literal">REQUIRE_ROW_FORMAT</code> is set for a
      replication channel, the replication applier does not create or
      drop temporary tables, and so does not set the
      <a class="link" href="server-administration.html#sysvar_pseudo_thread_id"><code class="literal">pseudo_thread_id</code></a> session system
      variable. It does not execute <code class="literal">LOAD DATA INFILE</code>
      instructions, and so does not attempt file operations to access or
      delete the temporary files associated with data loads (logged as a
      <code class="literal">Format_description_log_event</code>). It does not
      execute <code class="literal">INTVAR</code>, <code class="literal">RAND</code>, and
      <code class="literal">USER_VAR</code> events, which are used to reproduce
      the client's connection state for statement-based replication. (An
      exception is <code class="literal">USER_VAR</code> events that are
      associated with DDL queries, which are executed.) It does not
      execute any statements that are logged within DML transactions. If
      the replication applier detects any of these types of event while
      attempting to queue or apply a transaction, the event is not
      applied, and replication stops with an error.
    </p><p>
      You can set <code class="literal">REQUIRE_ROW_FORMAT</code> for a
      replication channel whether or not you set a
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account. The restrictions
      implemented when you set this option increase the security of the
      replication channel even without privilege checks. You can also
      specify the <code class="option">--require-row-format</code> option when you
      use <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>, to enforce row-based
      replication events in <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output.
    </p><p><b>Security Context. </b>
        By default, when a replication applier thread is started with a
        user account specified as the
        <code class="literal">PRIVILEGE_CHECKS_USER</code>, the security context
        is created using default roles, or with all roles if
        <a class="link" href="server-administration.html#sysvar_activate_all_roles_on_login"><code class="literal">activate_all_roles_on_login</code></a> is
        set to <code class="literal">ON</code>.
      </p><p>
      You can use roles to supply a general privilege set to accounts
      that are used as <code class="literal">PRIVILEGE_CHECKS_USER</code>
      accounts, as in the following example. Here, instead of granting
      the <a class="link" href="security.html#priv_insert"><code class="literal">INSERT</code></a> privilege for the
      <code class="literal">db1.cust</code> table directly to a user account as in
      the earlier example, this privilege is granted to the role
      <code class="literal">priv_repl_role</code> along with the
      <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege. The
      role is then used to grant the privilege set to two user accounts,
      both of which can now be used as
      <code class="literal">PRIVILEGE_CHECKS_USER</code> accounts:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; SET sql_log_bin = 0; 
mysql&gt; CREATE USER 'priv_repa'@'%.example.com' 
                  IDENTIFIED BY '<em class="replaceable"><code>password</code></em>' 
                  REQUIRE SSL; 
mysql&gt; CREATE USER 'priv_repb'@'%.example.com' 
                  IDENTIFIED BY '<em class="replaceable"><code>password</code></em>' 
                  REQUIRE SSL; 
mysql&gt; CREATE ROLE 'priv_repl_role'; 
mysql&gt; GRANT REPLICATION_APPLIER TO 'priv_repl_role'; 
mysql&gt; GRANT INSERT ON db1.cust TO 'priv_repl_role'; 
mysql&gt; GRANT 'priv_repl_role' TO
                  'priv_repa'@'%.example.com', 
                  'priv_repb'@'%.example.com'; 
mysql&gt; SET DEFAULT ROLE 'priv_repl_role' TO 
                  'priv_repa'@'%.example.com', 
                  'priv_repb'@'%.example.com';  
mysql&gt; SET sql_log_bin = 1;
</pre><p>
      Be aware that when the replication applier thread creates the
      security context, it checks the privileges for the
      <code class="literal">PRIVILEGE_CHECKS_USER</code> account, but does not
      carry out password validation, and does not carry out checks
      relating to account management, such as checking whether the
      account is locked. The security context that is created remains
      unchanged for the lifetime of the replication applier thread.
    </p><p><b>Limitation. </b>
        In MySQL 8.0.18 only, if the slave <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> is
        restarted immediately after issuing a <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET
        SLAVE</code></a> statement (due to a server crash or deliberate
        restart), the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
        setting, which is held in the
        <code class="literal">mysql.slave_relay_log_info</code> table, is lost and
        must be respecified. When you use privilege checks in that
        release, always verify that they are in place after a restart,
        and respecify them if required. From MySQL 8.0.19, the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account setting is
        preserved in this situation, so it is retrieved from the table
        and reapplied to the channel.

</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-privilege-checks-account"></a>17.3.3.1 Privileges For The Replication PRIVILEGE_CHECKS_USER Account</h4>
</div>
</div>
</div>
<p>
        The user account that is specified using the
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement as the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account for a
        replication channel must have the
        <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege,
        otherwise the replication applier thread does not start. As
        explained in <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>, the
        account requires further privileges that are sufficient to apply
        all the expected transactions expected on the replication
        channel. These privileges are checked only when relevant
        transactions are executed.
      </p><p>
        The use of row-based binary logging
        (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>) is strongly
        recommended for replication channels that are secured using a
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account. With
        statement-based binary logging, some administrator-level
        privileges might be required for the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account to execute
        transactions successfully. From MySQL 8.0.19, the
        <code class="literal">REQUIRE_ROW_FORMAT</code> setting can be applied to
        secured channels, which restricts the channel from executing
        events that would require these privileges.
      </p><p>
        The <a class="link" href="security.html#priv_replication-applier"><code class="literal">REPLICATION_APPLIER</code></a> privilege
        explicitly or implicitly allows the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account to carry out
        the following operations that a replication thread needs to
        perform:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Setting the value of the system variables
            <a class="link" href="replication.html#sysvar_gtid_next"><code class="literal">gtid_next</code></a>,
            <a class="link" href="replication.html#sysvar_original_commit_timestamp"><code class="literal">original_commit_timestamp</code></a>,
            <a class="link" href="replication.html#sysvar_original_server_version"><code class="literal">original_server_version</code></a>,
            <a class="link" href="replication.html#sysvar_immediate_server_version"><code class="literal">immediate_server_version</code></a>,
            and <a class="link" href="server-administration.html#sysvar_pseudo_slave_mode"><code class="literal">pseudo_slave_mode</code></a>, to
            apply appropriate metadata and behaviors when executing
            transactions.
          </p></li><li class="listitem"><p>
            Executing internal-use <a class="link" href="sql-statements.html#binlog" title="13.7.8.1 BINLOG Statement"><code class="literal">BINLOG</code></a>
            statements to apply <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output,
            provided that the account also has permission for the tables
            and operations in those statements.
          </p></li><li class="listitem"><p>
            Updating the system tables
            <code class="literal">mysql.gtid_executed</code>,
            <code class="literal">mysql.slave_relay_log_info</code>,
            <code class="literal">mysql.slave_worker_info</code>, and
            <code class="literal">mysql.slave_master_info</code>, to update
            replication metadata. (If events access these tables
            explicitly for other purposes, you must grant the
            appropriate privileges on the tables.)
          </p></li><li class="listitem"><p>
            Applying a binary log
            <code class="literal">Table_map_log_event</code>, which provides table
            metadata but does not make any database changes.
</p></li></ul>
</div>
<p>
        If the <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> option
        of the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement
        is set to the default of <code class="literal">STREAM</code>, the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account needs
        privileges sufficient to set restricted session variables, so
        that it can change the value of the
        <a class="link" href="server-administration.html#sysvar_sql_require_primary_key"><code class="literal">sql_require_primary_key</code></a> system
        variable for the duration of a session to match the setting
        replicated from the master. The
        <a class="link" href="security.html#priv_session-variables-admin"><code class="literal">SESSION_VARIABLES_ADMIN</code></a> privilege
        gives the account this capability. This privilege also allows
        the account to apply <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> output that
        was created using the
        <a class="link" href="programs.html#option_mysqlbinlog_disable-log-bin"><code class="option">--disable-log-bin</code></a> option. If
        you set <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> to
        either <code class="literal">ON</code> or <code class="literal">OFF</code>, the
        slave always uses that value for the
        <a class="link" href="server-administration.html#sysvar_sql_require_primary_key"><code class="literal">sql_require_primary_key</code></a> system
        variable in replication operations, and so does not need these
        session administration level privileges.
      </p><p>
        If table encryption is in use, the
        <a class="link" href="server-administration.html#sysvar_table_encryption_privilege_check"><code class="literal">table_encryption_privilege_check</code></a>
        system variable is set to <code class="literal">ON</code>, and the
        encryption setting for the tablespace involved in any event
        differs from the applying server's default encryption setting
        (specified by the
        <a class="link" href="server-administration.html#sysvar_default_table_encryption"><code class="literal">default_table_encryption</code></a> system
        variable), the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
        needs the <a class="link" href="security.html#priv_table-encryption-admin"><code class="literal">TABLE_ENCRYPTION_ADMIN</code></a>
        privilege in order to override the default encryption setting.
        It is strongly recommended that you do not grant this privilege.
        Instead, ensure that the default encryption setting on a
        replication slave matches the encryption status of the
        tablespaces that it replicates, and that replication group
        members have the same default encryption setting, so that the
        privilege is not needed.
      </p><p>
        In order to execute specific replicated transactions from the
        relay log, or transactions from <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>
        output as required, the <code class="literal">PRIVILEGE_CHECKS_USER</code>
        account must have the following privileges:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For a row insertion logged in row format (which are logged
            as a <code class="literal">Write_rows_log_event</code>), the
            <a class="link" href="security.html#priv_insert"><code class="literal">INSERT</code></a> privilege on the
            relevant table.
          </p></li><li class="listitem"><p>
            For a row update logged in row format (which are logged as
            an <code class="literal">Update_rows_log_event</code>), the
            <a class="link" href="security.html#priv_update"><code class="literal">UPDATE</code></a> privilege on the
            relevant table.
          </p></li><li class="listitem"><p>
            For a row deletion logged in row format (which are logged as
            a <code class="literal">Delete_rows_log_event</code>), the
            <a class="link" href="security.html#priv_delete"><code class="literal">DELETE</code></a> privilege on the
            relevant table.
</p></li></ul>
</div>
<p>
        If statement-based binary logging is in use (which is not
        recommended with a <code class="literal">PRIVILEGE_CHECKS_USER</code>
        account), for a transaction control statement such as
        <code class="literal">BEGIN</code> or <code class="literal">COMMIT</code> or DML
        logged in statement format (which are logged as a
        <code class="literal">Query_log_event</code>), the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account needs
        privileges to execute the statement contained in the event.
      </p><p>
        If <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> operations need to
        be carried out on the replication channel, use row-based binary
        logging (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>).
        With this logging format, the
        <a class="link" href="security.html#priv_file"><code class="literal">FILE</code></a> privilege is not needed to
        execute the event, so do not give the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account this privilege.
        The use of row-based binary logging is strongly recommended with
        replication channels that are secured using a
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account. If
        <code class="literal">REQUIRE_ROW_FORMAT</code> is set for the channel,
        row-based binary logging is required. The
        <code class="literal">Format_description_log_event</code>, which deletes
        any temporary files created by <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD
        DATA</code></a> events, is processed without privilege checks.
        For more information, see
        <a class="xref" href="replication.html#replication-features-load-data" title="17.5.1.19 Replication and LOAD DATA">Section 17.5.1.19, “Replication and LOAD DATA”</a>.
      </p><p>
        If the <a class="link" href="replication.html#sysvar_init_slave"><code class="literal">init_slave</code></a> system
        variable is set to specify one or more SQL statements to be
        executed when the SQL thread starts, the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account must have the
        privileges needed to execute these statements.
      </p><p>
        It is recommended that you never give any ACL privileges to the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account, including
        <a class="link" href="security.html#priv_create-user"><code class="literal">CREATE USER</code></a>,
        <a class="link" href="security.html#priv_create-role"><code class="literal">CREATE ROLE</code></a>,
        <a class="link" href="security.html#priv_drop-role"><code class="literal">DROP ROLE</code></a>, and
        <a class="link" href="security.html#priv_grant-option"><code class="literal">GRANT OPTION</code></a>, and do not permit
        the account to update the <code class="literal">mysql.user</code> table.
        With these privileges, the account could be used to create or
        modify user accounts on the server. To avoid ACL statements
        issued on the master being replicated to the secured channel for
        execution (where they will fail in the absence of these
        privileges), you can issue <code class="literal">SET sql_log_bin =
        0</code> before all ACL statements and <code class="literal">SET
        sql_log_bin = 1</code> after them, to omit the statements
        from the master's binary log. Alternatively, you can set a
        dedicated current database before executing all ACL statements,
        and use a replication filter
        (<a class="link" href="replication.html#option_mysqld_binlog-ignore-db"><code class="option">--binlog-ignore-db</code></a>) to filter
        out this database on the slave.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-privilege-checks-gr"></a>17.3.3.2 Privilege Checks For Group Replication Channels</h4>

</div>

</div>

</div>
<p>
        From MySQL 8.0.19, as well as securing asynchronous and
        semi-synchronous replication, you may choose to use a
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account to secure the
        two replication applier threads used by Group Replication. The
        <code class="literal">group_replication_applier</code> thread on each
        group member is used for applying the group's transactions, and
        the <code class="literal">group_replication_recovery</code> thread on each
        group member is used for state transfer from the binary log as
        part of distributed recovery when the member joins or rejoins
        the group.
      </p><p>
        To secure one of these threads, stop Group Replication, then
        issue the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
        statement with the <code class="literal">PRIVILEGE_CHECKS_USER</code>
        option, specifying <code class="literal">group_replication_applier</code>
        or <code class="literal">group_replication_recovery</code> as the channel
        name. For example:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP GROUP_REPLICATION;</code></strong>
mysql&gt; <strong class="userinput"><code>CHANGE MASTER TO PRIVILEGE_CHECKS_USER = 'gr_repl'@'%.example.com' FOR CHANNEL 'group_replication_recovery';</code></strong>
mysql&gt; <strong class="userinput"><code>START GROUP_REPLICATION;</code></strong> 
</pre><p>
        For Group Replication channels, the
        <code class="literal">REQUIRE_ROW_FORMAT</code> setting is automatically
        enabled when the channel is created, and cannot be disabled, so
        you do not need to specify this.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          In MySQL 8.0.19, ensure that you do not issue the
          <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement with
          the <code class="literal">PRIVILEGE_CHECKS_USER</code> option while
          Group Replication is running. This action causes the relay log
          files for the channel to be purged, which might cause the loss
          of transactions that have been received and queued in the
          relay log, but not yet applied.
</p>
</div>
<p>
        Group Replication requires every table that is to be replicated
        by the group to have a defined primary key, or primary key
        equivalent where the equivalent is a non-null unique key. Rather
        than using the checks carried out by the
        <a class="link" href="server-administration.html#sysvar_sql_require_primary_key"><code class="literal">sql_require_primary_key</code></a> system
        variable, Group Replication has its own built-in set of checks
        for primary keys or primary key equivalents. You may set the
        <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> option of the
        <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement to
        <code class="literal">ON</code> for a Group Replication channel. However,
        be aware that you might find some transactions that are
        permitted under Group Replication's built-in checks are not
        permitted under the checks carried out when you set
        <code class="literal">sql_require_primary_key = ON</code> or
        <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK = ON</code>. For
        this reason, new and upgraded Group Replication channels from
        MySQL 8.0.20 (when the option was introduced) have
        <code class="literal">REQUIRE_TABLE_PRIMARY_KEY_CHECK</code> set to the
        default of <code class="literal">STREAM</code>, rather than to
        <code class="literal">ON</code>.
      </p><p>
        If a remote cloning operation is used for distributed recovery
        in Group Replication (see
        <a class="xref" href="group-replication.html#group-replication-cloning" title="18.4.3.1 Cloning for Distributed Recovery">Section 18.4.3.1, “Cloning for Distributed Recovery”</a>), from MySQL 8.0.19,
        the <code class="literal">PRIVILEGE_CHECKS_USER</code> account and related
        settings from the donor are cloned to the joining member. If the
        joining member is set to start Group Replication on boot, it
        automatically uses the account for privilege checks on the
        appropriate replication channels.
      </p><p>
        In MySQL 8.0.18, due to a number of limitations, it is
        recommended that you do not use a
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account with Group
        Replication channels.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-privilege-checks-recover"></a>17.3.3.3 Recovering From Failed Replication Privilege Checks</h4>

</div>

</div>

</div>
<p>
        If a privilege check against the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account fails, the
        transaction is not executed and replication stops for the
        channel. Details of the error and the last applied transaction
        are recorded in the Performance Schema
        <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>
        table. Follow this procedure to recover from the error:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Identify the replicated event that caused the error and
            verify whether or not the event is expected and from a
            trusted source. You can use <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a>
            to retrieve and display the events that were logged around
            the time of the error. For instructions to do this, see
            <a class="xref" href="backup-and-recovery.html#point-in-time-recovery" title="7.5 Point-in-Time (Incremental) Recovery Using the Binary Log">Section 7.5, “Point-in-Time (Incremental) Recovery Using the Binary Log”</a>.
          </p></li><li class="listitem"><p>
            If the replicated event is not expected or is not from a
            known and trusted source, investigate the cause. If you can
            identify why the event took place and there are no security
            considerations, proceed to fix the error as described below.
          </p></li><li class="listitem"><p>
            If the <code class="literal">PRIVILEGE_CHECKS_USER</code> account
            should have been permitted to execute the transaction, but
            has been misconfigured, grant the missing privileges to the
            account and restart replication for the channel.
          </p></li><li class="listitem"><p>
            If the transaction needs to be executed and you have
            verified that it is trusted, but the
            <code class="literal">PRIVILEGE_CHECKS_USER</code> account should not
            have this privilege normally, you can grant the required
            privilege to the <code class="literal">PRIVILEGE_CHECKS_USER</code>
            account temporarily. After the replicated event has been
            applied, remove the privilege from the account, and take any
            necessary steps to ensure the event does not recur if it is
            avoidable.
          </p></li><li class="listitem"><p>
            If the transaction is an administrative action that should
            only have taken place on the master and not on the slave, or
            should only have taken place on a single replication group
            member, skip the transaction on the server or servers where
            it stopped replication, then issue
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> to restart
            replication on the channel. To avoid the situation in
            future, you could issue such administrative statements with
            <code class="literal">SET sql_log_bin = 0</code> before them and
            <code class="literal">SET sql_log_bin = 1</code> after them, so that
            they are not logged on the master.
          </p></li><li class="listitem"><p>
            If the transaction is a DDL or DML statement that should not
            have taken place on either the master or the slave, skip the
            transaction on the server or servers where it stopped
            replication, undo the transaction manually on the server
            where it originally took place, then issue
            <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> to restart
            replication.
</p></li></ol>
</div>
<p>
        To skip a transaction, if GTIDs are in use, commit an empty
        transaction that has the GTID of the failing transaction, for
        example:
      </p><pre data-lang="sql" class="programlisting">SET GTID_NEXT='aaa-bbb-ccc-ddd:N';
BEGIN;
COMMIT;
SET GTID_NEXT='AUTOMATIC';</pre><p>
        If GTIDs are not in use, issue a <code class="literal">SET GLOBAL
        sql_slave_skip_counter</code> statement to skip the event, as
        described in
        <a class="xref" href="sql-statements.html#set-global-sql-slave-skip-counter" title="13.4.2.5 SET GLOBAL sql_slave_skip_counter Statement">Section 13.4.2.5, “SET GLOBAL sql_slave_skip_counter Statement”</a>.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="replication-solutions"></a>17.4 Replication Solutions</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-solutions-backups">17.4.1 Using Replication for Backups</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-unexpected-slave-halt">17.4.2 Handling an Unexpected Halt of a Replication Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-rbr-monitoring">17.4.3 Monitoring Row-based Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-diffengines">17.4.4 Using Replication with Different Master and Slave Storage Engines</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-scaleout">17.4.5 Using Replication for Scale-Out</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-partitioning">17.4.6 Replicating Different Databases to Different Slaves</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-performance">17.4.7 Improving Replication Performance</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-switch">17.4.8 Switching Masters During Failover</a></span></dt><dt><span class="section"><a href="replication.html#replication-semisync">17.4.9 Semisynchronous Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-delayed">17.4.10 Delayed Replication</a></span></dt></dl>
</div>
<p>
    Replication can be used in many different environments for a range
    of purposes. This section provides general notes and advice on using
    replication for specific solution types.
  </p><p>
    For information on using replication in a backup environment,
    including notes on the setup, backup procedure, and files to back
    up, see <a class="xref" href="replication.html#replication-solutions-backups" title="17.4.1 Using Replication for Backups">Section 17.4.1, “Using Replication for Backups”</a>.
  </p><p>
    For advice and tips on using different storage engines on the master
    and slaves, see <a class="xref" href="replication.html#replication-solutions-diffengines" title="17.4.4 Using Replication with Different Master and Slave Storage Engines">Section 17.4.4, “Using Replication with Different Master and Slave Storage Engines”</a>.
  </p><p>
    Using replication as a scale-out solution requires some changes in
    the logic and operation of applications that use the solution. See
    <a class="xref" href="replication.html#replication-solutions-scaleout" title="17.4.5 Using Replication for Scale-Out">Section 17.4.5, “Using Replication for Scale-Out”</a>.
  </p><p>
    For performance or data distribution reasons, you may want to
    replicate different databases to different replication slaves. See
    <a class="xref" href="replication.html#replication-solutions-partitioning" title="17.4.6 Replicating Different Databases to Different Slaves">Section 17.4.6, “Replicating Different Databases to Different Slaves”</a>
  </p><p>
    As the number of replication slaves increases, the load on the
    master can increase and lead to reduced performance (because of the
    need to replicate the binary log to each slave). For tips on
    improving your replication performance, including using a single
    secondary server as a replication master, see
    <a class="xref" href="replication.html#replication-solutions-performance" title="17.4.7 Improving Replication Performance">Section 17.4.7, “Improving Replication Performance”</a>.
  </p><p>
    For guidance on switching masters, or converting slaves into masters
    as part of an emergency failover solution, see
    <a class="xref" href="replication.html#replication-solutions-switch" title="17.4.8 Switching Masters During Failover">Section 17.4.8, “Switching Masters During Failover”</a>.
  </p><p>
    For information on security measures specific to servers in a
    replication topology, see <a class="xref" href="replication.html#replication-security" title="17.3 Replication Security">Section 17.3, “Replication Security”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-backups"></a>17.4.1 Using Replication for Backups</h3>

</div>

</div>

</div>

<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-solutions-backups-mysqldump">17.4.1.1 Backing Up a Slave Using mysqldump</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-backups-rawdata">17.4.1.2 Backing Up Raw Data from a Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-solutions-backups-read-only">17.4.1.3 Backing Up a Master or Slave by Making It Read Only</a></span></dt></dl>
</div>
<p>
      To use replication as a backup solution, replicate data from the
      master to a slave, and then back up the data slave. The slave can
      be paused and shut down without affecting the running operation of
      the master, so you can produce an effective snapshot of
      <span class="quote">“<span class="quote">live</span>”</span> data that would otherwise require the master
      to be shut down.
    </p><p>
      How you back up a database depends on its size and whether you are
      backing up only the data, or the data and the replication slave
      state so that you can rebuild the slave in the event of failure.
      There are therefore two choices:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If you are using replication as a solution to enable you to
          back up the data on the master, and the size of your database
          is not too large, the <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> tool may be
          suitable. See
          <a class="xref" href="replication.html#replication-solutions-backups-mysqldump" title="17.4.1.1 Backing Up a Slave Using mysqldump">Section 17.4.1.1, “Backing Up a Slave Using mysqldump”</a>.
        </p></li><li class="listitem"><p>
          For larger databases, where <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> would
          be impractical or inefficient, you can back up the raw data
          files instead. Using the raw data files option also means that
          you can back up the binary and relay logs that will enable you
          to recreate the slave in the event of a slave failure. For
          more information, see
          <a class="xref" href="replication.html#replication-solutions-backups-rawdata" title="17.4.1.2 Backing Up Raw Data from a Slave">Section 17.4.1.2, “Backing Up Raw Data from a Slave”</a>.
</p></li></ul>
</div>
<p>
      Another backup strategy, which can be used for either master or
      slave servers, is to put the server in a read-only state. The
      backup is performed against the read-only server, which then is
      changed back to its usual read/write operational status. See
      <a class="xref" href="replication.html#replication-solutions-backups-read-only" title="17.4.1.3 Backing Up a Master or Slave by Making It Read Only">Section 17.4.1.3, “Backing Up a Master or Slave by Making It Read Only”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-solutions-backups-mysqldump"></a>17.4.1.1 Backing Up a Slave Using mysqldump</h4>
</div>
</div>
</div>
<p>
        Using <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> to create a copy of a
        database enables you to capture all of the data in the database
        in a format that enables the information to be imported into
        another instance of MySQL Server (see
        <a class="xref" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program">Section 4.5.4, “<span class="command"><strong>mysqldump</strong></span> — A Database Backup Program”</a>). Because the format of the
        information is SQL statements, the file can easily be
        distributed and applied to running servers in the event that you
        need access to the data in an emergency. However, if the size of
        your data set is very large, <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> may be
        impractical.
      </p><p>
        When using <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>, you should stop
        replication on the slave before starting the dump process to
        ensure that the dump contains a consistent set of data:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Stop the slave from processing requests. You can stop
            replication completely on the slave using
            <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a>:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin stop-slave</code></strong></pre><p>
            Alternatively, you can stop only the slave SQL thread to
            pause event execution:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysql -e 'STOP SLAVE SQL_THREAD;'</code></strong></pre><p>
            This enables the slave to continue to receive data change
            events from the master's binary log and store them in the
            relay logs using the I/O thread, but prevents the slave from
            executing these events and changing its data. Within busy
            replication environments, permitting the I/O thread to run
            during backup may speed up the catch-up process when you
            restart the slave SQL thread.
          </p></li><li class="listitem"><p>
            Run <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> to dump your databases. You
            may either dump all databases or select databases to be
            dumped. For example, to dump all databases:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqldump --all-databases &gt; fulldb.dump</code></strong></pre></li><li class="listitem"><p>
            Once the dump has completed, start slave operations again:
</p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin start-slave</code></strong></pre></li></ol>
</div>
<p>
        In the preceding example, you may want to add login credentials
        (user name, password) to the commands, and bundle the process up
        into a script that you can run automatically each day.
      </p><p>
        If you use this approach, make sure you monitor the slave
        replication process to ensure that the time taken to run the
        backup does not affect the slave's ability to keep up with
        events from the master. See
        <a class="xref" href="replication.html#replication-administration-status" title="17.1.7.1 Checking Replication Status">Section 17.1.7.1, “Checking Replication Status”</a>. If the
        slave is unable to keep up, you may want to add another slave
        and distribute the backup process. For an example of how to
        configure this scenario, see
        <a class="xref" href="replication.html#replication-solutions-partitioning" title="17.4.6 Replicating Different Databases to Different Slaves">Section 17.4.6, “Replicating Different Databases to Different Slaves”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-solutions-backups-rawdata"></a>17.4.1.2 Backing Up Raw Data from a Slave</h4>

</div>

</div>

</div>
<p>
        To guarantee the integrity of the files that are copied, backing
        up the raw data files on your MySQL replication slave should
        take place while your slave server is shut down. If the MySQL
        server is still running, background tasks may still be updating
        the database files, particularly those involving storage engines
        with background processes such as <code class="literal">InnoDB</code>.
        With <code class="literal">InnoDB</code>, these problems should be
        resolved during crash recovery, but since the slave server can
        be shut down during the backup process without affecting the
        execution of the master it makes sense to take advantage of this
        capability.
      </p><p>
        To shut down the server and back up the files:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Shut down the slave MySQL server:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqladmin shutdown</code></strong></pre></li><li class="listitem"><p>
            Copy the data files. You can use any suitable copying or
            archive utility, including <span class="command"><strong>cp</strong></span>,
            <span class="command"><strong>tar</strong></span> or <span class="command"><strong>WinZip</strong></span>. For
            example, assuming that the data directory is located under
            the current directory, you can archive the entire directory
            as follows:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>tar cf /tmp/dbbackup.tar ./data</code></strong></pre></li><li class="listitem"><p>
            Start the MySQL server again. Under Unix:
          </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqld_safe &amp;</code></strong></pre><p>
            Under Windows:
</p><pre data-lang="terminal" class="programlisting">C:\&gt; <strong class="userinput"><code>"C:\Program Files\MySQL\MySQL Server 8.0\bin\mysqld"</code></strong></pre></li></ol>
</div>
<p>
        Normally you should back up the entire data directory for the
        slave MySQL server. If you want to be able to restore the data
        and operate as a slave (for example, in the event of failure of
        the slave), in addition to the data, you need to have the master
        info repository and relay log info repository, and the relay log
        files. These items are needed to resume replication after you
        restore the slave's data. If tables have been used for the
        master info and relay log info repositories (see
        <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>), which is the default in MySQL
        8.0, these tables are backed up along with the data
        directory. If files have been used for the repositories, you
        must back these up separately. The relay log files must also be
        backed up separately if they have been placed in a different
        location to the data directory.
      </p><p>
        If you lose the relay logs but still have the
        <code class="filename">relay-log.info</code> file, you can check it to
        determine how far the SQL thread has executed in the master
        binary logs. Then you can use <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER
        TO</code></a> with the <code class="literal">MASTER_LOG_FILE</code> and
        <code class="literal">MASTER_LOG_POS</code> options to tell the slave to
        re-read the binary logs from that point. This requires that the
        binary logs still exist on the master server.
      </p><p>
        If your slave is replicating <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD
        DATA</code></a> statements, you should also back up any
        <code class="filename">SQL_LOAD-*</code> files that exist in the
        directory that the slave uses for this purpose. The slave needs
        these files to resume replication of any interrupted
        <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> operations. The
        location of this directory is the value of the
        <a class="link" href="replication.html#sysvar_slave_load_tmpdir"><code class="literal">slave_load_tmpdir</code></a> system
        variable. If the server was not started with that variable set,
        the directory location is the value of the
        <a class="link" href="server-administration.html#sysvar_tmpdir"><code class="literal">tmpdir</code></a> system variable.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-solutions-backups-read-only"></a>17.4.1.3 Backing Up a Master or Slave by Making It Read Only</h4>

</div>

</div>

</div>
<p>
        It is possible to back up either master or slave servers in a
        replication setup by acquiring a global read lock and
        manipulating the <a class="link" href="server-administration.html#sysvar_read_only"><code class="literal">read_only</code></a>
        system variable to change the read-only state of the server to
        be backed up:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Make the server read-only, so that it processes only
            retrievals and blocks updates.
          </p></li><li class="listitem"><p>
            Perform the backup.
          </p></li><li class="listitem"><p>
            Change the server back to its normal read/write state.
</p></li></ol>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          The instructions in this section place the server to be backed
          up in a state that is safe for backup methods that get the
          data from the server, such as <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>
          (see <a class="xref" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program">Section 4.5.4, “<span class="command"><strong>mysqldump</strong></span> — A Database Backup Program”</a>). You should not attempt to
          use these instructions to make a binary backup by copying
          files directly because the server may still have modified data
          cached in memory and not flushed to disk.
</p>
</div>
<p>
        The following instructions describe how to do this for a master
        server and for a slave server. For both scenarios discussed
        here, suppose that you have the following replication setup:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A master server M1
          </p></li><li class="listitem"><p>
            A slave server S1 that has M1 as its master
          </p></li><li class="listitem"><p>
            A client C1 connected to M1
          </p></li><li class="listitem"><p>
            A client C2 connected to S1
</p></li></ul>
</div>
<p>
        In either scenario, the statements to acquire the global read
        lock and manipulate the
        <a class="link" href="server-administration.html#sysvar_read_only"><code class="literal">read_only</code></a> variable are
        performed on the server to be backed up and do not propagate to
        any slaves of that server.
      </p><p>
        <span class="bold"><strong>Scenario 1: Backup with a Read-Only
        Master</strong></span>
      </p><p>
        Put the master M1 in a read-only state by executing these
        statements on it:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>FLUSH TABLES WITH READ LOCK;</code></strong>
mysql&gt; <strong class="userinput"><code>SET GLOBAL read_only = ON;</code></strong>
</pre><p>
        While M1 is in a read-only state, the following properties are
        true:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Requests for updates sent by C1 to M1 will block because the
            server is in read-only mode.
          </p></li><li class="listitem"><p>
            Requests for query results sent by C1 to M1 will succeed.
          </p></li><li class="listitem"><p>
            Making a backup on M1 is safe.
          </p></li><li class="listitem"><p>
            Making a backup on S1 is not safe. This server is still
            running, and might be processing the binary log or update
            requests coming from client C2.
</p></li></ul>
</div>
<p>
        While M1 is read only, perform the backup. For example, you can
        use <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>.
      </p><p>
        After the backup operation on M1 completes, restore M1 to its
        normal operational state by executing these statements:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET GLOBAL read_only = OFF;</code></strong>
mysql&gt; <strong class="userinput"><code>UNLOCK TABLES;</code></strong>
</pre><p>
        Although performing the backup on M1 is safe (as far as the
        backup is concerned), it is not optimal for performance because
        clients of M1 are blocked from executing updates.
      </p><p>
        This strategy applies to backing up a master server in a
        replication setup, but can also be used for a single server in a
        nonreplication setting.
      </p><p>
        <span class="bold"><strong>Scenario 2: Backup with a Read-Only
        Slave</strong></span>
      </p><p>
        Put the slave S1 in a read-only state by executing these
        statements on it:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>FLUSH TABLES WITH READ LOCK;</code></strong>
mysql&gt; <strong class="userinput"><code>SET GLOBAL read_only = ON;</code></strong>
</pre><p>
        While S1 is in a read-only state, the following properties are
        true:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The master M1 will continue to operate, so making a backup
            on the master is not safe.
          </p></li><li class="listitem"><p>
            The slave S1 is stopped, so making a backup on the slave S1
            is safe.
</p></li></ul>
</div>
<p>
        These properties provide the basis for a popular backup
        scenario: Having one slave busy performing a backup for a while
        is not a problem because it does not affect the entire network,
        and the system is still running during the backup. In
        particular, clients can still perform updates on the master
        server, which remains unaffected by backup activity on the
        slave.
      </p><p>
        While S1 is read only, perform the backup. For example, you can
        use <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a>.
      </p><p>
        After the backup operation on S1 completes, restore S1 to its
        normal operational state by executing these statements:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET GLOBAL read_only = OFF;</code></strong>
mysql&gt; <strong class="userinput"><code>UNLOCK TABLES;</code></strong>
</pre><p>
        After the slave is restored to normal operation, it again
        synchronizes to the master by catching up with any outstanding
        updates from the binary log of the master.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-unexpected-slave-halt"></a>17.4.2 Handling an Unexpected Halt of a Replication Slave</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm46444262343072"></a><a class="indexterm" name="idm46444262342000"></a><a class="indexterm" name="idm46444262340512"></a><p>
      In order for replication to be resilient to unexpected halts of
      the server (sometimes described as crash-safe) it must be possible
      for the slave to recover its state before halting. This section
      describes the impact of an unexpected halt of a slave during
      replication and how to configure a slave for the best chance of
      recovery to continue replication.
    </p><p>
      After an unexpected halt of a slave, upon restart the slave's SQL
      thread must recover which transactions have been executed already.
      The information required for recovery is stored in the slave's
      relay log info log. From MySQL 8.0, this log is created by default
      as an <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> table named
      <code class="literal">mysql.slave_relay_log_info</code> (with the system
      variable
      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a> set to
      the default of <code class="literal">TABLE</code>). By using this
      transactional storage engine the information is always recoverable
      upon restart.
    </p><p>
      Updates to the relay log info log table are committed together
      with the transactions, meaning that the slave's progress
      information recorded in that log is always consistent with what
      has been applied to the database, even in the event of an
      unexpected server halt. Previously, this information was stored by
      default in a file in the data directory that was updated after the
      transaction had been applied. This held the risk of losing
      synchrony with the master depending at which stage of processing a
      transaction the slave halted at, or even corruption of the file
      itself. The setting
      <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository = FILE</code></a>
      is now deprecated, and will be removed in a future release. For
      further information on the slave logs, see
      <a class="xref" href="replication.html#slave-logs" title="17.2.4 Replication Relay and Status Logs">Section 17.2.4, “Replication Relay and Status Logs”</a>.
    </p><p>
      When the relay log info log is stored in the
      <code class="literal">mysql.slave_relay_log_info</code> table, DML
      transactions and also atomic DDL make the following three updates
      together, atomically:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Apply the transaction on the database.
        </p></li><li class="listitem"><p>
          Update the replication positions in the
          <code class="literal">mysql.slave_relay_log_info</code> table.
        </p></li><li class="listitem"><p>
          Update the GTID in the mysql.gtid_executed table (when GTIDs
          are enabled and the binary log is disabled on the server).
</p></li></ul>
</div>
<p>
      In all other cases, including DDL statements that are not fully
      atomic, and exempted storage engines that do not support atomic
      DDL, the <code class="literal">mysql.slave_relay_log_info</code> table might
      be missing updates associated with replicated data if the server
      halts unexpectedly. Restoring updates in this case is a manual
      process. For details on atomic DDL support in MySQL
      8.0, and the resulting behavior for the replication
      of certain statements, see <a class="xref" href="sql-statements.html#atomic-ddl" title="13.1.1 Atomic Data Definition Statement Support">Section 13.1.1, “Atomic Data Definition Statement Support”</a>.
    </p><p>
      Exactly how a replication slave recovers from an unexpected halt
      is influenced by the chosen method of replication, whether the
      slave is single-threaded or multithreaded, the setting of
      variables such as
      <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a>, and whether
      features such as <code class="literal">MASTER_AUTO_POSITION</code> are being
      used.
    </p><p>
      The following table shows the impact of these different factors on
      how a single-threaded slave recovers from an unexpected halt.
</p>
<div class="table">
<a name="idm46444262319808"></a><p class="title"><b>Table 17.3 Factors Influencing Single-threaded Replication Slave Recovery</b></p>
<div class="table-contents">
<table frame="all" summary="Explains how different combinations of GTID use, MASTER_AUTO_POSITION setting, relay_log_recovery setting, relay_log_info_recovery setting, and type of crash (server or OS) impact on whether or not recovery is guaranteed, and whether or not the relay log remains intact."><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><thead><tr>
          <th scope="col"><p>
              GTID
            </p></th>
          <th scope="col"><p>
              MASTER_AUTO_POSITION
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a>
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
            </p></th>
          <th scope="col"><p>
              Crash type
            </p></th>
          <th scope="col"><p>
              Recovery guaranteed
            </p></th>
          <th scope="col"><p>
              Relay log impact
            </p></th>
        </tr></thead><tbody><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td><p>
              ON
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Remains
            </p></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
      As the table shows, when using a single-threaded slave the
      following configurations are most resilient to unexpected halts:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When using GTIDs and <code class="literal">MASTER_AUTO_POSITION</code>,
          set <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=1</code></a>.
          With this configuration the setting of
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a> and
          other variables does not impact on recovery. Note that to
          guarantee recovery,
          <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a> (which is the
          default) must also be set on the slave, so that the slave's
          binary log is synchronized to disk at each write. Otherwise,
          committed transactions might not be present in the slave's
          binary log.

        </p></li><li class="listitem"><p>
          When using file position based replication, set
          <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=1</code></a> and
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=TABLE</code></a>.

</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              During recovery the relay log is lost.
</p>
</div>
<p>
</p></li></ul>
</div>
<p>
      The following table shows the impact of these different factors on
      how a multithreaded slave recovers from an unexpected halt.
</p>
<div class="table">
<a name="idm46444262229728"></a><p class="title"><b>Table 17.4 Factors Influencing Multithreaded Replication Slave Recovery</b></p>
<div class="table-contents">
<table frame="all" summary="Explains how different combinations of GTID use, sync_relay_log setting, MASTER_AUTO_POSITION setting, relay_log_recovery setting, relay_log_info_recovery setting, and type of crash (server or OS) impact on whether or not recovery is guaranteed, and whether or not the relay log remains intact."><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><col width="1.0%" align="center"><thead><tr>
          <th scope="col"><p>
              GTID
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_sync_relay_log"><code class="literal">sync_relay_log</code></a>
            </p></th>
          <th scope="col"><p>
              <code class="literal">MASTER_AUTO_POSITION</code>
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a>
            </p></th>
          <th scope="col"><p>
              <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a>
            </p></th>
          <th scope="col"><p>
              Crash type
            </p></th>
          <th scope="col"><p>
              Recovery guaranteed
            </p></th>
          <th scope="col"><p>
              Relay log impact
            </p></th>
        </tr></thead><tbody><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              &gt;1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              &gt;1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              OFF
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td>Any</td>
          <td><p>
              ON
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Lost
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              TABLE
            </p></td>
          <td><p>
              Server
            </p></td>
          <td><p>
              Yes
            </p></td>
          <td><p>
              Remains
            </p></td>
        </tr><tr valign="middle">
          <td scope="row"><p>
              ON
            </p></td>
          <td><p>
              1
            </p></td>
          <td><p>
              OFF
            </p></td>
          <td><p>
              0
            </p></td>
          <td><p>
              Any
            </p></td>
          <td><p>
              OS
            </p></td>
          <td><p>
              No
            </p></td>
          <td><p>
              Remains
            </p></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
      As the table shows, when using a multithreaded slave the following
      configurations are most resilient to unexpected halts:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When using GTIDs and
          <code class="literal">MASTER_AUTO_POSITION=ON</code>, set
          <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=1</code></a>. With
          this configuration the setting of
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository</code></a> and
          other variables does not impact on recovery. From MySQL
          8.0.18, a multithreaded slave automatically skips relay log
          recovery when <code class="literal">MASTER_AUTO_POSITION</code> is set
          to <code class="literal">ON</code>, so the setting for
          <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery</code></a> makes no
          difference.

        </p></li><li class="listitem"><p>
          When using file position based replication, set
          <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=1</code></a>,
          <a class="link" href="replication.html#sysvar_sync_relay_log"><code class="literal">sync_relay_log=1</code></a>, and
          <a class="link" href="replication.html#sysvar_relay_log_info_repository"><code class="literal">relay_log_info_repository=TABLE</code></a>.

</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              During recovery the relay log is lost.
</p>
</div>
<p>
</p></li></ul>
</div>
<p>
      It is important to note the impact of
      <a class="link" href="replication.html#sysvar_sync_relay_log"><code class="literal">sync_relay_log=1</code></a>, which requires
      a write of to the relay log per transaction. Although this setting
      is the most resilient to an unexpected halt, with at most one
      unwritten transaction being lost, it also has the potential to
      greatly increase the load on storage. Without
      <a class="link" href="replication.html#sysvar_sync_relay_log"><code class="literal">sync_relay_log=1</code></a>, the effect of
      an unexpected halt depends on how the relay log is handled by the
      operating system. Also note that when
      <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=0</code></a>, the next
      time the slave is started after an unexpected halt the relay log
      is processed as part of recovery. After this process completes,
      the relay log is deleted.
    </p><p>
      An unexpected halt of a multithreaded replication slave using the
      recommended file position based replication configuration above
      may result in a relay log with transaction inconsistencies (gaps
      in the sequence of transactions) caused by the unexpected halt.
      See
      <a class="xref" href="replication.html#replication-features-transaction-inconsistencies" title="17.5.1.33 Replication and Transaction Inconsistencies">Section 17.5.1.33, “Replication and Transaction Inconsistencies”</a>.
      If the relay log recovery process encounters such transaction
      inconsistencies they are filled and the recovery process continues
      automatically.
    </p><p>
      When you are using multi-source replication and
      <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="literal">relay_log_recovery=1</code></a>, after
      restarting due to an unexpected halt all replication channels go
      through the relay log recovery process. Any inconsistencies found
      in the relay log due to an unexpected halt of a multithreaded
      slave are filled.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-rbr-monitoring"></a>17.4.3 Monitoring Row-based Replication</h3>

</div>

</div>

</div>
<p>
      The current progress of the replication applier (SQL) thread when
      using row-based replication is monitored through Performance
      Schema instrument stages, enabling you to track the processing of
      operations and check the amount of work completed and work
      estimated. When these Performance Schema instrument stages are
      enabled the <a class="link" href="performance-schema.html#events-stages-current-table" title="26.12.5.1 The events_stages_current Table"><code class="literal">events_stages_current</code></a>
      table shows stages for applier threads and their progress. For
      background information, see
      <a class="xref" href="performance-schema.html#performance-schema-stage-tables" title="26.12.5 Performance Schema Stage Event Tables">Section 26.12.5, “Performance Schema Stage Event Tables”</a>.
    </p><p>
      To track progress of all three row-based replication event types
      (write, update, delete):
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Enable the three Performance Schema stages by issuing:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>UPDATE performance_schema.setup_instruments SET ENABLED = 'YES'</code></strong>
    -&gt; <strong class="userinput"><code>WHERE NAME LIKE 'stage/sql/Applying batch of row changes%';</code></strong>
</pre></li><li class="listitem"><p>
          Wait for some events to be processed by the replication
          applier thread and then check progress by looking into the
          <a class="link" href="performance-schema.html#events-stages-current-table" title="26.12.5.1 The events_stages_current Table"><code class="literal">events_stages_current</code></a> table. For
          example to get progress for <code class="literal">update</code> events
          issue:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT WORK_COMPLETED, WORK_ESTIMATED FROM performance_schema.events_stages_current</code></strong>
    -&gt; <strong class="userinput"><code>WHERE EVENT_NAME LIKE 'stage/sql/Applying batch of row changes (update)'</code></strong>
</pre></li><li class="listitem"><p>
          If
          <a class="link" href="replication.html#sysvar_binlog_rows_query_log_events"><code class="literal">binlog_rows_query_log_events</code></a>
          is enabled, information about queries is stored in the binary
          log and is exposed in the <code class="literal">processlist_info</code>
          field. To see the original query that triggered this event:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT db, processlist_state, processlist_info FROM performance_schema.threads</code></strong>
    -&gt; <strong class="userinput"><code>WHERE processlist_state LIKE 'stage/sql/Applying batch of row changes%' AND thread_id = N;</code></strong>
</pre></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-diffengines"></a>17.4.4 Using Replication with Different Master and Slave Storage Engines</h3>

</div>

</div>

</div>
<p>
      It does not matter for the replication process whether the source
      table on the master and the replicated table on the slave use
      different engine types. In fact, the
      <a class="link" href="server-administration.html#sysvar_default_storage_engine"><code class="literal">default_storage_engine</code></a> system
      variable is not replicated.
    </p><p>
      This provides a number of benefits in the replication process in
      that you can take advantage of different engine types for
      different replication scenarios. For example, in a typical
      scale-out scenario (see
      <a class="xref" href="replication.html#replication-solutions-scaleout" title="17.4.5 Using Replication for Scale-Out">Section 17.4.5, “Using Replication for Scale-Out”</a>), you want to use
      <code class="literal">InnoDB</code> tables on the master to take advantage
      of the transactional functionality, but use
      <code class="literal">MyISAM</code> on the slaves where transaction support
      is not required because the data is only read. When using
      replication in a data-logging environment you may want to use the
      <code class="literal">Archive</code> storage engine on the slave.
    </p><p>
      Configuring different engines on the master and slave depends on
      how you set up the initial replication process:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If you used <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> to create the
          database snapshot on your master, you could edit the dump file
          text to change the engine type used on each table.
        </p><p>
          Another alternative for <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> is to
          disable engine types that you do not want to use on the slave
          before using the dump to build the data on the slave. For
          example, you can add the
          <a class="link" href="innodb-storage-engine.html#option_mysqld_innodb"><code class="option">--skip-federated</code></a>
          option on your slave to disable the
          <code class="literal">FEDERATED</code> engine. If a specific engine does
          not exist for a table to be created, MySQL will use the
          default engine type, usually <code class="literal">MyISAM</code>. (This
          requires that the
          <a class="link" href="server-administration.html#sqlmode_no_engine_substitution"><code class="literal">NO_ENGINE_SUBSTITUTION</code></a> SQL
          mode is not enabled.) If you want to disable additional
          engines in this way, you may want to consider building a
          special binary to be used on the slave that only supports the
          engines you want.
        </p></li><li class="listitem"><p>
          If you are using raw data files (a binary backup) to set up
          the slave, you will be unable to change the initial table
          format. Instead, use <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
          TABLE</code></a> to change the table types after the slave has
          been started.
        </p></li><li class="listitem"><p>
          For new master/slave replication setups where there are
          currently no tables on the master, avoid specifying the engine
          type when creating new tables.
</p></li></ul>
</div>
<p>
      If you are already running a replication solution and want to
      convert your existing tables to another engine type, follow these
      steps:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Stop the slave from running replication updates:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>STOP SLAVE;</code></strong>
</pre><p>
          This will enable you to change engine types without
          interruptions.
        </p></li><li class="listitem"><p>
          Execute an <code class="literal">ALTER TABLE ...
          ENGINE='<em class="replaceable"><code>engine_type</code></em>'</code> for
          each table to be changed.
        </p></li><li class="listitem"><p>
          Start the slave replication process again:
        </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre></li></ol>
</div>
<p>
      Although the
      <a class="link" href="server-administration.html#sysvar_default_storage_engine"><code class="literal">default_storage_engine</code></a> variable
      is not replicated, be aware that <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
      TABLE</code></a> and <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a>
      statements that include the engine specification will be correctly
      replicated to the slave. For example, if you have a CSV table and
      you execute:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>ALTER TABLE csvtable Engine='MyISAM';</code></strong>
</pre><p>
      The above statement will be replicated to the slave and the engine
      type on the slave will be converted to <code class="literal">MyISAM</code>,
      even if you have previously changed the table type on the slave to
      an engine other than CSV. If you want to retain engine differences
      on the master and slave, you should be careful to use the
      <a class="link" href="server-administration.html#sysvar_default_storage_engine"><code class="literal">default_storage_engine</code></a> variable
      on the master when creating a new table. For example, instead of:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CREATE TABLE tablea (columna int) Engine=MyISAM;</code></strong>
</pre><p>
      Use this format:
    </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET default_storage_engine=MyISAM;</code></strong>
mysql&gt; <strong class="userinput"><code>CREATE TABLE tablea (columna int);</code></strong>
</pre><p>
      When replicated, the
      <a class="link" href="server-administration.html#sysvar_default_storage_engine"><code class="literal">default_storage_engine</code></a> variable
      will be ignored, and the <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
      TABLE</code></a> statement will execute on the slave using the
      slave's default engine.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-scaleout"></a>17.4.5 Using Replication for Scale-Out</h3>

</div>

</div>

</div>
<p>
      You can use replication as a scale-out solution; that is, where
      you want to split up the load of database queries across multiple
      database servers, within some reasonable limitations.
    </p><p>
      Because replication works from the distribution of one master to
      one or more slaves, using replication for scale-out works best in
      an environment where you have a high number of reads and low
      number of writes/updates. Most websites fit into this category,
      where users are browsing the website, reading articles, posts, or
      viewing products. Updates only occur during session management, or
      when making a purchase or adding a comment/message to a forum.
    </p><p>
      Replication in this situation enables you to distribute the reads
      over the replication slaves, while still enabling your web servers
      to communicate with the replication master when a write is
      required. You can see a sample replication layout for this
      scenario in <a class="xref" href="replication.html#figure_replication-scaleout" title="Figure 17.1 Using Replication to Improve Performance During Scale-Out">Figure 17.1, “Using Replication to Improve Performance During Scale-Out”</a>.
</p>
<div class="figure">
<a name="figure_replication-scaleout"></a><p class="title"><b>Figure 17.1 Using Replication to Improve Performance During Scale-Out</b></p>
<div class="figure-contents">

<div class="mediaobject">
<img src="images/scaleout.png" width="687" height="341" alt="Incoming requests from clients are directed to a load balancer, which distributes client data among a number of web clients. Writes made by web clients are directed to a single MySQL master server, and reads made by web clients are directed to one of three MySQL slave servers. Replication takes place from the MySQL master server to the three MySQL slave servers.">
</div>

</div>

</div>
<br class="figure-break"><p>
      If the part of your code that is responsible for database access
      has been properly abstracted/modularized, converting it to run
      with a replicated setup should be very smooth and easy. Change the
      implementation of your database access to send all writes to the
      master, and to send reads to either the master or a slave. If your
      code does not have this level of abstraction, setting up a
      replicated system gives you the opportunity and motivation to
      clean it up. Start by creating a wrapper library or module that
      implements the following functions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">safe_writer_connect()</code>
        </p></li><li class="listitem"><p>
          <code class="literal">safe_reader_connect()</code>
        </p></li><li class="listitem"><p>
          <code class="literal">safe_reader_statement()</code>
        </p></li><li class="listitem"><p>
          <code class="literal">safe_writer_statement()</code>
</p></li></ul>
</div>
<p>
      <code class="literal">safe_</code> in each function name means that the
      function takes care of handling all error conditions. You can use
      different names for the functions. The important thing is to have
      a unified interface for connecting for reads, connecting for
      writes, doing a read, and doing a write.
    </p><p>
      Then convert your client code to use the wrapper library. This may
      be a painful and scary process at first, but it pays off in the
      long run. All applications that use the approach just described
      are able to take advantage of a master/slave configuration, even
      one involving multiple slaves. The code is much easier to
      maintain, and adding troubleshooting options is trivial. You need
      modify only one or two functions (for example, to log how long
      each statement took, or which statement among those issued gave
      you an error).
    </p><p>
      If you have written a lot of code, you may want to automate the
      conversion task by writing a conversion script. Ideally, your code
      uses consistent programming style conventions. If not, then you
      are probably better off rewriting it anyway, or at least going
      through and manually regularizing it to use a consistent style.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-partitioning"></a>17.4.6 Replicating Different Databases to Different Slaves</h3>

</div>

</div>

</div>
<p>
      There may be situations where you have a single master and want to
      replicate different databases to different slaves. For example,
      you may want to distribute different sales data to different
      departments to help spread the load during data analysis. A sample
      of this layout is shown in
      <a class="xref" href="replication.html#figure_replication-multi-db" title="Figure 17.2 Using Replication to Replicate Databases to Separate Replication Slaves">Figure 17.2, “Using Replication to Replicate Databases to Separate Replication Slaves”</a>.
</p>
<div class="figure">
<a name="figure_replication-multi-db"></a><p class="title"><b>Figure 17.2 Using Replication to Replicate Databases to Separate Replication Slaves</b></p>
<div class="figure-contents">

<div class="mediaobject">
<img src="images/multi-db.png" width="424" height="178" alt="The MySQL master server has three databases, databaseA, databaseB, and databaseC. DatabaseA is replicated only to MySQL Slave 1, DatabaseB is replicated only to MySQL Slave 2, and DatabaseC is replicated only to MySQL Slave 3.">
</div>

</div>

</div>
<br class="figure-break"><p>
      You can achieve this separation by configuring the master and
      slaves as normal, and then limiting the binary log statements that
      each slave processes by using the
      <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
      configuration option on each slave.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        You should <span class="emphasis"><em>not</em></span> use
        <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> for this
        purpose when using statement-based replication, since
        statement-based replication causes this option's effects to
        vary according to the database that is currently selected. This
        applies to mixed-format replication as well, since this enables
        some updates to be replicated using the statement-based format.
      </p><p>
        However, it should be safe to use
        <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a> for this
        purpose if you are using row-based replication only, since in
        this case the currently selected database has no effect on the
        option's operation.
</p>
</div>
<p>
      For example, to support the separation as shown in
      <a class="xref" href="replication.html#figure_replication-multi-db" title="Figure 17.2 Using Replication to Replicate Databases to Separate Replication Slaves">Figure 17.2, “Using Replication to Replicate Databases to Separate Replication Slaves”</a>, you should
      configure each replication slave as follows, before executing
      <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a>:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Replication slave 1 should use
          <code class="option">--replicate-wild-do-table=databaseA.%</code>.
        </p></li><li class="listitem"><p>
          Replication slave 2 should use
          <code class="option">--replicate-wild-do-table=databaseB.%</code>.
        </p></li><li class="listitem"><p>
          Replication slave 3 should use
          <code class="option">--replicate-wild-do-table=databaseC.%</code>.
</p></li></ul>
</div>
<p>
      Each slave in this configuration receives the entire binary log
      from the master, but executes only those events from the binary
      log that apply to the databases and tables included by the
      <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a> option in
      effect on that slave.
    </p><p>
      If you have data that must be synchronized to the slaves before
      replication starts, you have a number of choices:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Synchronize all the data to each slave, and delete the
          databases, tables, or both that you do not want to keep.
        </p></li><li class="listitem"><p>
          Use <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> to create a separate dump
          file for each database and load the appropriate dump file on
          each slave.
        </p></li><li class="listitem"><p>
          Use a raw data file dump and include only the specific files
          and databases that you need for each slave.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            This does not work with <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a>
            databases unless you use
            <a class="link" href="innodb-storage-engine.html#sysvar_innodb_file_per_table"><code class="literal">innodb_file_per_table</code></a>.
</p>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-performance"></a>17.4.7 Improving Replication Performance</h3>

</div>

</div>

</div>
<p>
      As the number of slaves connecting to a master increases, the
      load, although minimal, also increases, as each slave uses a
      client connection to the master. Also, as each slave must receive
      a full copy of the master binary log, the network load on the
      master may also increase and create a bottleneck.
    </p><p>
      If you are using a large number of slaves connected to one master,
      and that master is also busy processing requests (for example, as
      part of a scale-out solution), then you may want to improve the
      performance of the replication process.
    </p><p>
      One way to improve the performance of the replication process is
      to create a deeper replication structure that enables the master
      to replicate to only one slave, and for the remaining slaves to
      connect to this primary slave for their individual replication
      requirements. A sample of this structure is shown in
      <a class="xref" href="replication.html#figure_replication-performance" title="Figure 17.3 Using an Additional Replication Host to Improve Performance">Figure 17.3, “Using an Additional Replication Host to Improve Performance”</a>.
</p>
<div class="figure">
<a name="figure_replication-performance"></a><p class="title"><b>Figure 17.3 Using an Additional Replication Host to Improve Performance</b></p>
<div class="figure-contents">

<div class="mediaobject">
<img src="images/submaster-performance.png" width="534" height="179" alt="The server MySQL Master 1 replicates to the server MySQL Master 2, which in turn replicates to the servers MySQL Slave 1, MySQL Slave 2, and MySQL Slave 3.">
</div>

</div>

</div>
<br class="figure-break"><p>
      For this to work, you must configure the MySQL instances as
      follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Master 1 is the primary master where all changes and updates
          are written to the database. Binary logging is enabled on both
          masters, which is the default.
        </p></li><li class="listitem"><p>
          Master 2 is the slave to the Master 1 that provides the
          replication functionality to the remainder of the slaves in
          the replication structure. Master 2 is the only machine
          permitted to connect to Master 1. Master 2 has the
          <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a> option
          enabled (which is the default). With this option, replication
          instructions from Master 1 are also written to Master 2's
          binary log so that they can then be replicated to the true
          slaves.
        </p></li><li class="listitem"><p>
          Slave 1, Slave 2, and Slave 3 act as slaves to Master 2, and
          replicate the information from Master 2, which actually
          consists of the upgrades logged on Master 1.
</p></li></ul>
</div>
<p>
      The above solution reduces the client load and the network
      interface load on the primary master, which should improve the
      overall performance of the primary master when used as a direct
      database solution.
    </p><p>
      If your slaves are having trouble keeping up with the replication
      process on the master, there are a number of options available:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If possible, put the relay logs and the data files on
          different physical drives. To do this, set the
          <a class="link" href="replication.html#sysvar_relay_log"><code class="literal">relay_log</code></a> system variable to
          specify the location of the relay log.
        </p></li><li class="listitem"><p>
          If heavy disk I/O activity for reads of the binary log file
          and relay log files is an issue, consider increasing the value
          of the <a class="link" href="replication.html#sysvar_rpl_read_size"><code class="literal">rpl_read_size</code></a> system
          variable. This system variable controls the minimum amount of
          data read from the log files, and increasing it might reduce
          file reads and I/O stalls when the file data is not currently
          cached by the operating system. Note that a buffer the size of
          this value is allocated for each thread that reads from the
          binary log and relay log files, including dump threads on
          masters and coordinator threads on slaves. Setting a large
          value might therefore have an impact on memory consumption for
          servers.
        </p></li><li class="listitem"><p>
          If the slaves are significantly slower than the master, you
          may want to divide up the responsibility for replicating
          different databases to different slaves. See
          <a class="xref" href="replication.html#replication-solutions-partitioning" title="17.4.6 Replicating Different Databases to Different Slaves">Section 17.4.6, “Replicating Different Databases to Different Slaves”</a>.
        </p></li><li class="listitem"><p>
          If your master makes use of transactions and you are not
          concerned about transaction support on your slaves, use
          <code class="literal">MyISAM</code> or another nontransactional engine
          on the slaves. See
          <a class="xref" href="replication.html#replication-solutions-diffengines" title="17.4.4 Using Replication with Different Master and Slave Storage Engines">Section 17.4.4, “Using Replication with Different Master and Slave Storage Engines”</a>.
        </p></li><li class="listitem"><p>
          If your slaves are not acting as masters, and you have a
          potential solution in place to ensure that you can bring up a
          master in the event of failure, then you can disable the
          <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a> system
          variable on the slaves. This prevents <span class="quote">“<span class="quote">dumb</span>”</span>
          slaves from also logging events they have executed into their
          own binary log.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-solutions-switch"></a>17.4.8 Switching Masters During Failover</h3>

</div>

</div>

</div>
<p>
      You can tell a slave to change to a new master using the
      <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statement. The
      slave does not check whether the databases on the master are
      compatible with those on the slave; it simply begins reading and
      executing events from the specified coordinates in the new
      master's binary log. In a failover situation, all the servers
      in the group are typically executing the same events from the same
      binary log file, so changing the source of the events should not
      affect the structure or integrity of the database, provided that
      you exercise care in making the change.
    </p><p>
      Slaves should be run with binary logging enabled (the
      <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--log-bin</code></a> option), which is the
      default. If you are not using GTIDs for replication, then the
      slaves should also be run with
      <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> (logging
      slave updates is the default). In this way, the slave is ready to
      become a master without restarting the slave
      <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>. Assume that you have the structure
      shown in <a class="xref" href="replication.html#figure_replication-redundancy-before" title="Figure 17.4 Redundancy Using Replication, Initial Structure">Figure 17.4, “Redundancy Using Replication, Initial Structure”</a>.
</p>
<div class="figure">
<a name="figure_replication-redundancy-before"></a><p class="title"><b>Figure 17.4 Redundancy Using Replication, Initial Structure</b></p>
<div class="figure-contents">

<div class="mediaobject">
<img src="images/redundancy-before.png" width="504" height="353" alt="Two web clients direct both database reads and database writes to a single MySQL master server. The MySQL master server replicates to MySQL Slave 1, MySQL Slave 2, and MySQL Slave 3.">
</div>

</div>

</div>
<br class="figure-break"><p>
      In this diagram, the <code class="literal">MySQL Master</code> holds the
      master database, the <code class="literal">MySQL Slave</code> hosts are
      replication slaves, and the <code class="literal">Web Client</code> machines
      are issuing database reads and writes. Web clients that issue only
      reads (and would normally be connected to the slaves) are not
      shown, as they do not need to switch to a new server in the event
      of failure. For a more detailed example of a read/write scale-out
      replication structure, see
      <a class="xref" href="replication.html#replication-solutions-scaleout" title="17.4.5 Using Replication for Scale-Out">Section 17.4.5, “Using Replication for Scale-Out”</a>.
    </p><p>
      Each MySQL Slave (<code class="literal">Slave 1</code>, <code class="literal">Slave
      2</code>, and <code class="literal">Slave 3</code>) is a slave running
      with binary logging enabled, and with
      <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a>. Because
      updates received by a slave from the master are not logged in the
      binary log when
      <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> is
      specified, the binary log on each slave is empty initially. If for
      some reason <code class="literal">MySQL Master</code> becomes unavailable,
      you can pick one of the slaves to become the new master. For
      example, if you pick <code class="literal">Slave 1</code>, all <code class="literal">Web
      Clients</code> should be redirected to <code class="literal">Slave
      1</code>, which writes the updates to its binary log.
      <code class="literal">Slave 2</code> and <code class="literal">Slave 3</code> should
      then replicate from <code class="literal">Slave 1</code>.
    </p><p>
      The reason for running the slave with
      <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates=OFF</code></a> is to
      prevent slaves from receiving updates twice in case you cause one
      of the slaves to become the new master. If <code class="literal">Slave
      1</code> has <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a>
      enabled, which is the default, it writes any updates that it
      receives from <code class="literal">Master</code> in its own binary log.
      This means that, when <code class="literal">Slave 2</code> changes from
      <code class="literal">Master</code> to <code class="literal">Slave 1</code> as its
      master, it may receive updates from <code class="literal">Slave 1</code>
      that it has already received from <code class="literal">Master</code>.
    </p><p>
      Make sure that all slaves have processed any statements in their
      relay log. On each slave, issue <code class="literal">STOP SLAVE
      IO_THREAD</code>, then check the output of
      <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW PROCESSLIST</code></a> until you see
      <code class="literal">Has read all relay log</code>. When this is true for
      all slaves, they can be reconfigured to the new setup. On the
      slave <code class="literal">Slave 1</code> being promoted to become the
      master, issue <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> and
      <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a>.
    </p><p>
      On the other slaves <code class="literal">Slave 2</code> and <code class="literal">Slave
      3</code>, use <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> and
      <code class="literal">CHANGE MASTER TO MASTER_HOST='Slave1'</code> (where
      <code class="literal">'Slave1'</code> represents the real host name of
      <code class="literal">Slave 1</code>). To use <code class="literal">CHANGE MASTER
      TO</code>, add all information about how to connect to
      <code class="literal">Slave 1</code> from <code class="literal">Slave 2</code> or
      <code class="literal">Slave 3</code> (<em class="replaceable"><code>user</code></em>,
      <em class="replaceable"><code>password</code></em>,
      <em class="replaceable"><code>port</code></em>). When issuing the <code class="literal">CHANGE
      MASTER TO</code> statement in this, there is no need to specify
      the name of the <code class="literal">Slave 1</code> binary log file or log
      position to read from, since the first binary log file and
      position 4, are the defaults. Finally, execute
      <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> on <code class="literal">Slave
      2</code> and <code class="literal">Slave 3</code>.
    </p><p>
      Once the new replication setup is in place, you need to tell each
      <code class="literal">Web Client</code> to direct its statements to
      <code class="literal">Slave 1</code>. From that point on, all update
      statements sent by <code class="literal">Web Client</code> to <code class="literal">Slave
      1</code> are written to the binary log of <code class="literal">Slave
      1</code>, which then contains every update statement sent to
      <code class="literal">Slave 1</code> since <code class="literal">Master</code> died.
    </p><p>
      The resulting server structure is shown in
      <a class="xref" href="replication.html#figure_replication-redundancy-after" title="Figure 17.5 Redundancy Using Replication, After Master Failure">Figure 17.5, “Redundancy Using Replication, After Master Failure”</a>.
</p>
<div class="figure">
<a name="figure_replication-redundancy-after"></a><p class="title"><b>Figure 17.5 Redundancy Using Replication, After Master Failure</b></p>
<div class="figure-contents">

<div class="mediaobject">
<img src="images/redundancy-after.png" width="538" height="432" alt="The MySQL master server has failed, and is no longer connected into the replication topology. The two web clients now direct both database reads and database writes to MySQL Slave 1, which is the new master. MySQL Slave 1 replicates to MySQL Slave 2 and MySQL Slave 3.">
</div>

</div>

</div>
<br class="figure-break"><p>
      When <code class="literal">Master</code> becomes available again, you should
      make it a slave of <code class="literal">Slave 1</code>. To do this, issue
      on <code class="literal">Master</code> the same <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE
      MASTER TO</code></a> statement as that issued on <code class="literal">Slave
      2</code> and <code class="literal">Slave 3</code> previously.
      <code class="literal">Master</code> then becomes a slave of <code class="literal">S1ave
      1</code> and picks up the <code class="literal">Web Client</code> writes
      that it missed while it was offline.
    </p><p>
      To make <code class="literal">Master</code> a master again, use the
      preceding procedure as if <code class="literal">Slave 1</code> was
      unavailable and <code class="literal">Master</code> was to be the new
      master. During this procedure, do not forget to run
      <a class="link" href="sql-statements.html#reset-master" title="13.4.1.2 RESET MASTER Statement"><code class="literal">RESET MASTER</code></a> on
      <code class="literal">Master</code> before making <code class="literal">Slave
      1</code>, <code class="literal">Slave 2</code>, and <code class="literal">Slave
      3</code> slaves of <code class="literal">Master</code>. If you fail to do
      this, the slaves may pick up stale writes from the <code class="literal">Web
      Client</code> applications dating from before the point at
      which <code class="literal">Master</code> became unavailable.
    </p><p>
      You should be aware that there is no synchronization between
      slaves, even when they share the same master, and thus some slaves
      might be considerably ahead of others. This means that in some
      cases the procedure outlined in the previous example might not
      work as expected. In practice, however, relay logs on all slaves
      should be relatively close together.
    </p><p>
      One way to keep applications informed about the location of the
      master is to have a dynamic DNS entry for the master. With
      <code class="literal">bind</code> you can use <code class="filename">nsupdate</code>
      to update the DNS dynamically.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-semisync"></a>17.4.9 Semisynchronous Replication</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-semisync-interface">17.4.9.1 Semisynchronous Replication Administrative Interface</a></span></dt><dt><span class="section"><a href="replication.html#replication-semisync-installation">17.4.9.2 Semisynchronous Replication Installation and Configuration</a></span></dt><dt><span class="section"><a href="replication.html#replication-semisync-monitoring">17.4.9.3 Semisynchronous Replication Monitoring</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444261866848"></a><a class="indexterm" name="idm46444261865792"></a><p>
      In addition to the built-in asynchronous replication, MySQL
      8.0 supports an interface to semisynchronous
      replication that is implemented by plugins. This section discusses
      what semisynchronous replication is and how it works. The
      following sections cover the administrative interface to
      semisynchronous replication and how to install, configure, and
      monitor it.
    </p><p>
      MySQL replication by default is asynchronous. The master writes
      events to its binary log but does not know whether or when a slave
      has retrieved and processed them. With asynchronous replication,
      if the master crashes, transactions that it has committed might
      not have been transmitted to any slave. Consequently, failover
      from master to slave in this case may result in failover to a
      server that is missing transactions relative to the master.
    </p><p>
      Semisynchronous replication can be used as an alternative to
      asynchronous replication:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          A slave indicates whether it is semisynchronous-capable when
          it connects to the master.
        </p></li><li class="listitem"><p>
          If semisynchronous replication is enabled on the master side
          and there is at least one semisynchronous slave, a thread that
          performs a transaction commit on the master blocks and waits
          until at least one semisynchronous slave acknowledges that it
          has received all events for the transaction, or until a
          timeout occurs.
        </p></li><li class="listitem"><p>
          The slave acknowledges receipt of a transaction's events only
          after the events have been written to its relay log and
          flushed to disk.
        </p></li><li class="listitem"><p>
          If a timeout occurs without any slave having acknowledged the
          transaction, the master reverts to asynchronous replication.
          When at least one semisynchronous slave catches up, the master
          returns to semisynchronous replication.
        </p></li><li class="listitem"><p>
          Semisynchronous replication must be enabled on both the master
          and slave sides. If semisynchronous replication is disabled on
          the master, or enabled on the master but on no slaves, the
          master uses asynchronous replication.
</p></li></ul>
</div>
<p>
      While the master is blocking (waiting for acknowledgment from a
      slave), it does not return to the session that performed the
      transaction. When the block ends, the master returns to the
      session, which then can proceed to execute other statements. At
      this point, the transaction has committed on the master side, and
      receipt of its events has been acknowledged by at least one slave.
    </p><p>
      The number of slave acknowledgments the master must receive per
      transaction before proceeding is configurable using the
      <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>
      system variable. The default value is 1.
    </p><p>
      Blocking also occurs after rollbacks that are written to the
      binary log, which occurs when a transaction that modifies
      nontransactional tables is rolled back. The rolled-back
      transaction is logged even though it has no effect for
      transactional tables because the modifications to the
      nontransactional tables cannot be rolled back and must be sent to
      slaves.
    </p><p>
      For statements that do not occur in transactional context (that
      is, when no transaction has been started with
      <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">START
      TRANSACTION</code></a> or
      <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET autocommit =
      0</code></a>), autocommit is enabled and each statement commits
      implicitly. With semisynchronous replication, the master blocks
      for each such statement, just as it does for explicit transaction
      commits.
    </p><p>
      To understand what the <span class="quote">“<span class="quote">semi</span>”</span> in
      <span class="quote">“<span class="quote">semisynchronous replication</span>”</span> means, compare it with
      asynchronous and fully synchronous replication:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          With asynchronous replication, the master writes events to its
          binary log and slaves request them when they are ready. There
          is no guarantee that any event will ever reach any slave.
        </p></li><li class="listitem"><p>
          With fully synchronous replication, when a master commits a
          transaction, all slaves also will have committed the
          transaction before the master returns to the session that
          performed the transaction. The drawback of this is that there
          might be a lot of delay to complete a transaction.
        </p></li><li class="listitem"><p>
          Semisynchronous replication falls between asynchronous and
          fully synchronous replication. The master waits only until at
          least one slave has received and logged the events. It does
          not wait for all slaves to acknowledge receipt, and it
          requires only receipt, not that the events have been fully
          executed and committed on the slave side.
</p></li></ul>
</div>
<p>
      Compared to asynchronous replication, semisynchronous replication
      provides improved data integrity because when a commit returns
      successfully, it is known that the data exists in at least two
      places. Until a semisynchronous master receives acknowledgment
      from the number of slaves configured by
      <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_for_slave_count"><code class="literal">rpl_semi_sync_master_wait_for_slave_count</code></a>,
      the transaction is on hold and not committed.
    </p><p>
      Semisynchronous replication also places a rate limit on busy
      sessions by constraining the speed at which binary log events can
      be sent from master to slave. When one user is too busy, this will
      slow it down, which is useful in some deployment situations.
    </p><p>
      Semisynchronous replication does have some performance impact
      because commits are slower due to the need to wait for slaves.
      This is the tradeoff for increased data integrity. The amount of
      slowdown is at least the TCP/IP roundtrip time to send the commit
      to the slave and wait for the acknowledgment of receipt by the
      slave. This means that semisynchronous replication works best for
      close servers communicating over fast networks, and worst for
      distant servers communicating over slow networks.
    </p><p>
      The
      <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_wait_point"><code class="literal">rpl_semi_sync_master_wait_point</code></a>
      system variable controls the point at which a semisynchronous
      replication master waits for slave acknowledgment of transaction
      receipt before returning a status to the client that committed the
      transaction. These values are permitted:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">AFTER_SYNC</code> (the default): The master writes
          each transaction to its binary log and the slave, and syncs
          the binary log to disk. The master waits for slave
          acknowledgment of transaction receipt after the sync. Upon
          receiving acknowledgment, the master commits the transaction
          to the storage engine and returns a result to the client,
          which then can proceed.
        </p></li><li class="listitem"><p>
          <code class="literal">AFTER_COMMIT</code>: The master writes each
          transaction to its binary log and the slave, syncs the binary
          log, and commits the transaction to the storage engine. The
          master waits for slave acknowledgment of transaction receipt
          after the commit. Upon receiving acknowledgment, the master
          returns a result to the client, which then can proceed.
</p></li></ul>
</div>
<p>
      The replication characteristics of these settings differ as
      follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          With <code class="literal">AFTER_SYNC</code>, all clients see the
          committed transaction at the same time: After it has been
          acknowledged by the slave and committed to the storage engine
          on the master. Thus, all clients see the same data on the
          master.
        </p><p>
          In the event of master failure, all transactions committed on
          the master have been replicated to the slave (saved to its
          relay log). A crash of the master and failover to the slave is
          lossless because the slave is up to date.
        </p></li><li class="listitem"><p>
          With <code class="literal">AFTER_COMMIT</code>, the client issuing the
          transaction gets a return status only after the server commits
          to the storage engine and receives slave acknowledgment. After
          the commit and before slave acknowledgment, other clients can
          see the committed transaction before the committing client.
        </p><p>
          If something goes wrong such that the slave does not process
          the transaction, then in the event of a master crash and
          failover to the slave, it is possible that such clients will
          see a loss of data relative to what they saw on the master.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-semisync-interface"></a>17.4.9.1 Semisynchronous Replication Administrative Interface</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261827840"></a><p>
        The administrative interface to semisynchronous replication has
        several components:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Two plugins implement semisynchronous capability. There is
            one plugin for the master side and one for the slave side.
          </p></li><li class="listitem"><p>
            System variables control plugin behavior. Some examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled"><code class="literal">rpl_semi_sync_master_enabled</code></a>
              </p><p>
                Controls whether semisynchronous replication is enabled
                on the master. To enable or disable the plugin, set this
                variable to 1 or 0, respectively. The default is 0
                (off).
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>
              </p><p>
                A value in milliseconds that controls how long the
                master waits on a commit for acknowledgment from a slave
                before timing out and reverting to asynchronous
                replication. The default value is 10000 (10 seconds).
              </p></li><li class="listitem"><p>
                <a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_enabled"><code class="literal">rpl_semi_sync_slave_enabled</code></a>
              </p><p>
                Similar to
                <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled"><code class="literal">rpl_semi_sync_master_enabled</code></a>,
                but controls the slave plugin.
</p></li></ul>
</div>
<p>
            All
            <code class="literal">rpl_semi_sync_<em class="replaceable"><code>xxx</code></em></code>
            system variables are described at
            <a class="xref" href="server-administration.html#server-system-variables" title="5.1.8 Server System Variables">Section 5.1.8, “Server System Variables”</a>.
          </p></li><li class="listitem"><p>
            Status variables enable semisynchronous replication
            monitoring. Some examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_clients"><code class="literal">Rpl_semi_sync_master_clients</code></a>
              </p><p>
                The number of semisynchronous slaves.
              </p></li><li class="listitem"><p>
                <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_status"><code class="literal">Rpl_semi_sync_master_status</code></a>
              </p><p>
                Whether semisynchronous replication currently is
                operational on the master. The value is 1 if the plugin
                has been enabled and a commit acknowledgment has not
                occurred. It is 0 if the plugin is not enabled or the
                master has fallen back to asynchronous replication due
                to commit acknowledgment timeout.
              </p></li><li class="listitem"><p>
                <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_no_tx"><code class="literal">Rpl_semi_sync_master_no_tx</code></a>
              </p><p>
                The number of commits that were not acknowledged
                successfully by a slave.
              </p></li><li class="listitem"><p>
                <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_yes_tx"><code class="literal">Rpl_semi_sync_master_yes_tx</code></a>
              </p><p>
                The number of commits that were acknowledged
                successfully by a slave.
              </p></li><li class="listitem"><p>
                <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_slave_status"><code class="literal">Rpl_semi_sync_slave_status</code></a>
              </p><p>
                Whether semisynchronous replication currently is
                operational on the slave. This is 1 if the plugin has
                been enabled and the slave I/O thread is running, 0
                otherwise.
</p></li></ul>
</div>
<p>
            All
            <code class="literal">Rpl_semi_sync_<em class="replaceable"><code>xxx</code></em></code>
            status variables are described at
            <a class="xref" href="server-administration.html#server-status-variables" title="5.1.10 Server Status Variables">Section 5.1.10, “Server Status Variables”</a>.
</p></li></ul>
</div>
<p>
        The system and status variables are available only if the
        appropriate master or slave plugin has been installed with
        <a class="link" href="sql-statements.html#install-plugin" title="13.7.4.4 INSTALL PLUGIN Statement"><code class="literal">INSTALL PLUGIN</code></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-semisync-installation"></a>17.4.9.2 Semisynchronous Replication Installation and Configuration</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261792352"></a><a class="indexterm" name="idm46444261790896"></a><p>
        Semisynchronous replication is implemented using plugins, so the
        plugins must be installed into the server to make them
        available. After a plugin has been installed, you control it by
        means of the system variables associated with it. These system
        variables are unavailable until the associated plugin has been
        installed.
      </p><p>
        This section describes how to install the semisynchronous
        replication plugins. For general information about installing
        plugins, see <a class="xref" href="server-administration.html#plugin-loading" title="5.6.1 Installing and Uninstalling Plugins">Section 5.6.1, “Installing and Uninstalling Plugins”</a>.
      </p><p>
        To use semisynchronous replication, the following requirements
        must be satisfied:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The capability of installing plugins requires a MySQL server
            that supports dynamic loading. To verify this, check that
            the value of the
            <a class="link" href="server-administration.html#sysvar_have_dynamic_loading"><code class="literal">have_dynamic_loading</code></a> system
            variable is <code class="literal">YES</code>. Binary distributions
            should support dynamic loading.
          </p></li><li class="listitem"><p>
            Replication must already be working, see
            <a class="xref" href="replication.html#replication-configuration" title="17.1 Configuring Replication">Section 17.1, “Configuring Replication”</a>.
          </p></li><li class="listitem"><p>
            There must not be multiple replication channels configured.
            Semisynchronous replication is only compatible with the
            default replication channel. See
            <a class="xref" href="replication.html#replication-channels" title="17.2.3 Replication Channels">Section 17.2.3, “Replication Channels”</a>.
</p></li></ul>
</div>
<p>
        To set up semisynchronous replication, use the following
        instructions. The <a class="link" href="sql-statements.html#install-plugin" title="13.7.4.4 INSTALL PLUGIN Statement"><code class="literal">INSTALL PLUGIN</code></a>,
        <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET
        GLOBAL</code></a>, <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>, and
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statements mentioned
        here require the
        <a class="link" href="security.html#priv_replication-slave-admin"><code class="literal">REPLICATION_SLAVE_ADMIN</code></a> privilege
        (or the deprecated <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a>
        privilege).
      </p><p>
        MySQL distributions include semisynchronous replication plugin
        files for the master side and the slave side.
      </p><p>
        To be usable by a master or slave server, the appropriate plugin
        library file must be located in the MySQL plugin directory (the
        directory named by the
        <a class="link" href="server-administration.html#sysvar_plugin_dir"><code class="literal">plugin_dir</code></a> system variable). If
        necessary, configure the plugin directory location by setting
        the value of <a class="link" href="server-administration.html#sysvar_plugin_dir"><code class="literal">plugin_dir</code></a> at
        server startup.
      </p><p>
        The plugin library file base names are
        <code class="literal">semisync_master</code> and
        <code class="literal">semisync_slave</code>. The file name suffix differs
        per platform (for example, <code class="filename">.so</code> for Unix and
        Unix-like systems, <code class="filename">.dll</code> for Windows).
      </p><p>
        The master plugin library file must be present in the plugin
        directory of the master server. The slave plugin library file
        must be present in the plugin directory of each slave server.
      </p><p>
        To load the plugins, use the <a class="link" href="sql-statements.html#install-plugin" title="13.7.4.4 INSTALL PLUGIN Statement"><code class="literal">INSTALL
        PLUGIN</code></a> statement on the master and on each slave that
        is to be semisynchronous (adjust the <code class="filename">.so</code>
        suffix for your platform as necessary).
      </p><p>
        On the master:
      </p><pre data-lang="sql" class="programlisting">INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so';</pre><p>
        On each slave:
      </p><pre data-lang="sql" class="programlisting">INSTALL PLUGIN rpl_semi_sync_slave SONAME 'semisync_slave.so';</pre><p>
        If an attempt to install a plugin results in an error on Linux
        similar to that shown here, you must install
        <code class="literal">libimf</code>:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so';</code></strong>
ERROR 1126 (HY000): Can't open shared library
'/usr/local/mysql/lib/plugin/semisync_master.so'
(errno: 22 libimf.so: cannot open shared object file:
No such file or directory)
</pre><p>
        You can obtain <code class="literal">libimf</code> from
        <a class="ulink" href="https://dev.mysql.com/downloads/os-linux.html" target="_top">https://dev.mysql.com/downloads/os-linux.html</a>.
      </p><p>
        To see which plugins are installed, use the
        <a class="link" href="sql-statements.html#show-plugins" title="13.7.7.25 SHOW PLUGINS Statement"><code class="literal">SHOW PLUGINS</code></a> statement, or query
        the <a class="link" href="information-schema.html#plugins-table" title="25.21 The INFORMATION_SCHEMA PLUGINS Table"><code class="literal">INFORMATION_SCHEMA.PLUGINS</code></a>
        table.
      </p><p>
        To verify plugin installation, examine the
        <a class="link" href="information-schema.html#plugins-table" title="25.21 The INFORMATION_SCHEMA PLUGINS Table"><code class="literal">INFORMATION_SCHEMA.PLUGINS</code></a> table or
        use the <a class="link" href="sql-statements.html#show-plugins" title="13.7.7.25 SHOW PLUGINS Statement"><code class="literal">SHOW PLUGINS</code></a> statement
        (see <a class="xref" href="server-administration.html#obtaining-plugin-information" title="5.6.2 Obtaining Server Plugin Information">Section 5.6.2, “Obtaining Server Plugin Information”</a>). For
        example:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT PLUGIN_NAME, PLUGIN_STATUS</code></strong>
       <strong class="userinput"><code>FROM INFORMATION_SCHEMA.PLUGINS</code></strong>
       <strong class="userinput"><code>WHERE PLUGIN_NAME LIKE '%semi%';</code></strong>
+----------------------+---------------+
| PLUGIN_NAME          | PLUGIN_STATUS |
+----------------------+---------------+
| rpl_semi_sync_master | ACTIVE        |
+----------------------+---------------+
</pre><p>
        If the plugin fails to initialize, check the server error log
        for diagnostic messages.
      </p><p>
        After a semisynchronous replication plugin has been installed,
        it is disabled by default. The plugins must be enabled both on
        the master side and the slave side to enable semisynchronous
        replication. If only one side is enabled, replication will be
        asynchronous.
      </p><p>
        To control whether an installed plugin is enabled, set the
        appropriate system variables. You can set these variables at
        runtime using <a class="link" href="sql-statements.html#set-variable" title="13.7.6.1 SET Syntax for Variable Assignment"><code class="literal">SET
        GLOBAL</code></a>, or at server startup on the command line or in
        an option file.
      </p><p>
        At runtime, these master-side system variables are available:
      </p><pre data-lang="sql" class="programlisting">SET GLOBAL rpl_semi_sync_master_enabled = {0|1};
SET GLOBAL rpl_semi_sync_master_timeout = <em class="replaceable"><code>N</code></em>;
</pre><p>
        On the slave side, this system variable is available:
      </p><pre data-lang="sql" class="programlisting">SET GLOBAL rpl_semi_sync_slave_enabled = {0|1};</pre><p>
        For
        <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled"><code class="literal">rpl_semi_sync_master_enabled</code></a> or
        <a class="link" href="replication.html#sysvar_rpl_semi_sync_slave_enabled"><code class="literal">rpl_semi_sync_slave_enabled</code></a>,
        the value should be 1 to enable semisynchronous replication or 0
        to disable it. By default, these variables are set to 0.
      </p><p>
        For
        <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_timeout"><code class="literal">rpl_semi_sync_master_timeout</code></a>,
        the value <em class="replaceable"><code>N</code></em> is given in milliseconds.
        The default value is 10000 (10 seconds).
      </p><p>
        If you enable semisynchronous replication on a slave at runtime,
        you must also start the slave I/O thread (stopping it first if
        it is already running) to cause the slave to connect to the
        master and register as a semisynchronous slave:
      </p><pre data-lang="sql" class="programlisting">STOP SLAVE IO_THREAD;
START SLAVE IO_THREAD;</pre><p>
        If the I/O thread is already running and you do not restart it,
        the slave continues to use asynchronous replication.
      </p><p>
        At server startup, the variables that control semisynchronous
        replication can be set as command-line options or in an option
        file. A setting listed in an option file takes effect each time
        the server starts. For example, you can set the variables in
        <code class="filename">my.cnf</code> files on the master and slave sides
        as follows.
      </p><p>
        On the master:
      </p><pre data-lang="ini" class="programlisting">[mysqld]
rpl_semi_sync_master_enabled=1
rpl_semi_sync_master_timeout=1000 # 1 second</pre><p>
        On each slave:
      </p><pre data-lang="ini" class="programlisting">[mysqld]
rpl_semi_sync_slave_enabled=1</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-semisync-monitoring"></a>17.4.9.3 Semisynchronous Replication Monitoring</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444426201776"></a><p>
        The plugins for the semisynchronous replication capability
        expose several system and status variables that you can examine
        to determine its configuration and operational state.
      </p><p>
        The system variable reflect how semisynchronous replication is
        configured. To check their values, use <a class="link" href="sql-statements.html#show-variables" title="13.7.7.39 SHOW VARIABLES Statement"><code class="literal">SHOW
        VARIABLES</code></a>:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'rpl_semi_sync%';</code></strong>
</pre><p>
        The status variables enable you to monitor the operation of
        semisynchronous replication. To check their values, use
        <a class="link" href="sql-statements.html#show-status" title="13.7.7.35 SHOW STATUS Statement"><code class="literal">SHOW STATUS</code></a>:
      </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SHOW STATUS LIKE 'Rpl_semi_sync%';</code></strong>
</pre><p>
        When the master switches between asynchronous or semisynchronous
        replication due to commit-blocking timeout or a slave catching
        up, it sets the value of the
        <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_status"><code class="literal">Rpl_semi_sync_master_status</code></a>
        status variable appropriately. Automatic fallback from
        semisynchronous to asynchronous replication on the master means
        that it is possible for the
        <a class="link" href="replication.html#sysvar_rpl_semi_sync_master_enabled"><code class="literal">rpl_semi_sync_master_enabled</code></a>
        system variable to have a value of 1 on the master side even
        when semisynchronous replication is in fact not operational at
        the moment. You can monitor the
        <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_status"><code class="literal">Rpl_semi_sync_master_status</code></a>
        status variable to determine whether the master currently is
        using asynchronous or semisynchronous replication.
      </p><p>
        To see how many semisynchronous slaves are connected, check
        <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_clients"><code class="literal">Rpl_semi_sync_master_clients</code></a>.
      </p><p>
        The number of commits that have been acknowledged successfully
        or unsuccessfully by slaves are indicated by the
        <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_yes_tx"><code class="literal">Rpl_semi_sync_master_yes_tx</code></a>
        and <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_master_no_tx"><code class="literal">Rpl_semi_sync_master_no_tx</code></a>
        variables.
      </p><p>
        On the slave side,
        <a class="link" href="server-administration.html#statvar_Rpl_semi_sync_slave_status"><code class="literal">Rpl_semi_sync_slave_status</code></a>
        indicates whether semisynchronous replication currently is
        operational.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-delayed"></a>17.4.10 Delayed Replication</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm46444426180096"></a><a class="indexterm" name="idm46444426179024"></a><a class="indexterm" name="idm46444426177536"></a><a class="indexterm" name="idm46444426176448"></a><p>
      MySQL supports delayed replication such that a slave server
      deliberately executes transactions later than the master by at
      least a specified amount of time. This section describes how to
      configure a replication delay on a slave, and how to monitor
      replication delay.
    </p><p>
      In MySQL 8.0, the method of delaying replication
      depends on two timestamps,
      <code class="literal">immediate_commit_timestamp</code> and
      <code class="literal">original_commit_timestamp</code> (see
      <a class="xref" href="replication.html#replication-delayed-timestamps" title="Replication Delay Timestamps">Replication Delay Timestamps</a>). If all servers
      in the replication topology are running MySQL 8.0.1 or above,
      delayed replication is measured using these timestamps. If either
      the immediate master or slave is not using these timestamps, the
      implementation of delayed replication from MySQL 5.7 is used (see
      <a class="ulink" href="https://dev.mysql.com/doc/refman/5.7/en/replication-delayed.html" target="_top">Delayed Replication</a>). This section
      describes delayed replication between servers which are all using
      these timestamps.

    </p><p>
      The default replication delay is 0 seconds. Use the
      <code class="literal">CHANGE MASTER TO MASTER_DELAY=N</code> statement to
      set the delay to <em class="replaceable"><code>N</code></em> seconds. A
      transaction received from the master is not executed until at
      least <em class="replaceable"><code>N</code></em> seconds later than its commit
      on the immediate master. The delay happens per transaction (not
      event as in previous MySQL versions) and the actual delay is
      imposed only on <code class="literal">gtid_log_event</code> or
      <code class="literal">anonymous_gtid_log_event</code>. The other events in
      the transaction always follow these events without any waiting
      time imposed on them.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> and
        <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> take effect
        immediately and ignore any delay. <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET
        SLAVE</code></a> resets the delay to 0.
</p>
</div>
<p>
      The <a class="link" href="performance-schema.html#replication-applier-configuration-table" title="26.12.11.3 The replication_applier_configuration Table"><code class="literal">replication_applier_configuration</code></a>
      Performance Schema table contains the
      <code class="literal">DESIRED_DELAY</code> column which shows the delay
      configured using the <code class="literal">MASTER_DELAY</code> option. The
      <a class="link" href="performance-schema.html#replication-applier-status-table" title="26.12.11.4 The replication_applier_status Table"><code class="literal">replication_applier_status</code></a>
      Performance Schema table contains the
      <code class="literal">REMAINING_DELAY</code> column which shows the number
      of delay seconds remaining.
    </p><p>
      Delayed replication can be used for several purposes:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          To protect against user mistakes on the master. With a delay
          you can roll back a delayed slave to the time just before the
          mistake.
        </p></li><li class="listitem"><p>
          To test how the system behaves when there is a lag. For
          example, in an application, a lag might be caused by a heavy
          load on the slave. However, it can be difficult to generate
          this load level. Delayed replication can simulate the lag
          without having to simulate the load. It can also be used to
          debug conditions related to a lagging slave.
        </p></li><li class="listitem"><p>
          To inspect what the database looked like in the past, without
          having to reload a backup. For example, by configuring a slave
          with a delay of one week, if you then need to see what the
          database looked like before the last few days' worth of
          development, the delayed slave can be inspected.
</p></li></ul>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="replication-delayed-timestamps"></a>Replication Delay Timestamps</h4>

</div>

</div>

</div>
<p>
        MySQL 8.0 provides a new method for measuring delay
        (also referred to as replication lag) in replication topologies
        that depends on the following timestamps associated with the
        GTID of each transaction (instead of each event) written to the
        binary log.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">original_commit_timestamp</code>: the number of
            microseconds since epoch when the transaction was written
            (committed) to the binary log of the original master.
          </p></li><li class="listitem"><p>
            <code class="literal">immediate_commit_timestamp</code>: the number of
            microseconds since epoch when the transaction was written
            (committed) to the binary log of the immediate master.
</p></li></ul>
</div>
<p>
        The output of <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> displays these
        timestamps in two formats, microseconds from epoch and also
        <code class="literal">TIMESTAMP</code> format, which is based on the user
        defined time zone for better readability. For example:
      </p><pre data-lang="none" class="programlisting">#170404 10:48:05 server id 1  end_log_pos 233 CRC32 0x016ce647     GTID    last_committed=0   
\ sequence_number=1    original_committed_timestamp=1491299285661130    immediate_commit_timestamp=1491299285843771
# original_commit_timestamp=1491299285661130 (2017-04-04 10:48:05.661130 WEST)
# immediate_commit_timestamp=1491299285843771 (2017-04-04 10:48:05.843771 WEST)
 /*!80001 SET @@SESSION.original_commit_timestamp=1491299285661130*//*!*/;
   SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1'/*!*/;
# at 233</pre><p>
        As a rule, the <code class="literal">original_commit_timestamp</code> is
        always the same on all replicas where the transaction is
        applied. In master-slave replication, the
        <code class="literal">original_commit_timestamp</code> of a transaction in
        the (original) master’s binary log is always the same as its
        <code class="literal">immediate_commit_timestamp</code>. In the slave’s
        relay log, the <code class="literal">original_commit_timestamp</code> and
        <code class="literal">immediate_commit_timestamp</code> of the transaction
        are the same as in the master’s binary log; whereas in its own
        binary log, the transaction’s
        <code class="literal">immediate_commit_timestamp</code> corresponds to
        when the slave committed the transaction.
      </p><p>
        In a Group Replication setup, when the original master is a
        member of a group, the
        <code class="literal">original_commit_timestamp</code> is generated when
        the transaction is ready to be committed. In other words, when
        it finished executing on the original master and its write set
        is ready to be sent to all members of the group for
        certification. Therefore, the same
        <code class="literal">original_commit_timestamp</code> is replicated to
        all servers (regardless of whether it is a group member or slave
        replicating from a member) applying the transaction and each
        stores in its binary log the local commit time using
        <code class="literal">immediate_commit_timestamp</code>.
      </p><p>
        View change events, which are exclusive to Group Replication,
        are a special case. Transactions containing these events are
        generated by each server but share the same GTID (so, they are
        not first executed in a master and then replicated to the group,
        but all members of the group execute and apply the same
        transaction). Since there is no original master, these
        transactions have their
        <code class="literal">original_commit_timestamp</code> set to zero.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="replication-delayed-monitoring"></a>Monitoring Replication Delay</h4>

</div>

</div>

</div>
<p>
        One of the most common ways to monitor replication delay (lag)
        in previous MySQL versions was by relying on the
        <code class="literal">Seconds_Behind_Master</code> field in the output of
        <code class="literal">SHOW SLAVE STATUS</code>. However, this metric is
        not suitable when using replication topologies more complex than
        the traditional master-slave setup, such as Group Replication.
        The addition of <code class="literal">immediate_commit_timestamp</code>
        and <code class="literal">original_commit_timestamp</code> to MySQL 8
        provides a much finer degree of information about replication
        delay. The recommended method to monitor replication delay in a
        topology that supports these timestamps is using the following
        Performance Schema tables.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="performance-schema.html#replication-connection-status-table" title="26.12.11.2 The replication_connection_status Table"><code class="literal">replication_connection_status</code></a>:
            current status of the connection to the master, provides
            information on the last and current transaction the
            connection thread queued into the relay log.
          </p></li><li class="listitem"><p>
            <a class="link" href="performance-schema.html#replication-applier-status-by-coordinator-table" title="26.12.11.5 The replication_applier_status_by_coordinator Table"><code class="literal">replication_applier_status_by_coordinator</code></a>:
            current status of the coordinator thread that only displays
            information when using a multithreaded slave, provides
            information on the last transaction buffered by the
            coordinator thread to a worker’s queue, as well as the
            transaction it is currently buffering.
          </p></li><li class="listitem"><p>
            <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>:
            current status of the thread(s) applying transactions
            received from the master, provides information about the
            transactions applied by the applier thread, or by each
            worker when using a multithreaded slave.
</p></li></ul>
</div>
<p>
        Using these tables you can monitor information about the last
        transaction the corresponding thread processed and the
        transaction that thread is currently processing. This
        information comprises:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            a transaction’s GTID
          </p></li><li class="listitem"><p>
            a transaction's <code class="literal">original_commit_timestamp</code>
            and <code class="literal">immediate_commit_timestamp</code>, retrieved
            from the slave’s relay log
          </p></li><li class="listitem"><p>
            the time a thread started processing a transaction
          </p></li><li class="listitem"><p>
            for the last processed transaction, the time the thread
            finished processing it
</p></li></ul>
</div>
<p>
        In addition to the Performance Schema tables, the output of
        <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> has three
        fields that show:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">SQL_Delay</code>: A nonnegative integer
            indicating the replication delay configured using
            <code class="literal">CHANGE MASTER TO MASTER_DELAY=N</code>, measured
            in seconds.
          </p></li><li class="listitem"><p>
            <code class="literal">SQL_Remaining_Delay</code>: When
            <code class="literal">Slave_SQL_Running_State</code> is
            <code class="literal">Waiting until MASTER_DELAY seconds after master
            executed event</code>, this field contains an integer
            indicating the number of seconds left of the delay. At other
            times, this field is <code class="literal">NULL</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">Slave_SQL_Running_State</code>: A string
            indicating the state of the SQL thread (analogous to
            <code class="literal">Slave_IO_State</code>). The value is identical
            to the <code class="literal">State</code> value of the SQL thread as
            displayed by <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
            PROCESSLIST</code></a>.
</p></li></ul>
</div>
<p>
        When the slave SQL thread is waiting for the delay to elapse
        before executing an event, <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
        PROCESSLIST</code></a> displays its <code class="literal">State</code>
        value as <code class="literal">Waiting until MASTER_DELAY seconds after
        master executed event</code>.
</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="replication-notes"></a>17.5 Replication Notes and Tips</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-features">17.5.1 Replication Features and Issues</a></span></dt><dt><span class="section"><a href="replication.html#replication-compatibility">17.5.2 Replication Compatibility Between MySQL Versions</a></span></dt><dt><span class="section"><a href="replication.html#replication-upgrade">17.5.3 Upgrading a Replication Setup</a></span></dt><dt><span class="section"><a href="replication.html#replication-problems">17.5.4 Troubleshooting Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-bugs">17.5.5 How to Report Replication Bugs or Problems</a></span></dt></dl>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-features"></a>17.5.1 Replication Features and Issues</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="replication.html#replication-features-auto-increment">17.5.1.1 Replication and AUTO_INCREMENT</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-blackhole">17.5.1.2 Replication and BLACKHOLE Tables</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-charset">17.5.1.3 Replication and Character Sets</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-checksum-table">17.5.1.4 Replication and CHECKSUM TABLE</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-create-alter-drop-server">17.5.1.5 Replication of CREATE SERVER, ALTER SERVER, and DROP SERVER</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-create-if-not-exists">17.5.1.6 Replication of CREATE ... IF NOT EXISTS Statements</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-create-select">17.5.1.7 Replication of CREATE TABLE ... SELECT Statements</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-current-user">17.5.1.8 Replication of CURRENT_USER()</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-differing-tables">17.5.1.9 Replication with Differing Table Definitions on Master and Slave</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-directory">17.5.1.10 Replication and DIRECTORY Table Options</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-drop-if-exists">17.5.1.11 Replication of DROP ... IF EXISTS Statements</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-floatvalues">17.5.1.12 Replication and Floating-Point Values</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-flush">17.5.1.13 Replication and FLUSH</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-functions">17.5.1.14 Replication and System Functions</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-fractional-seconds">17.5.1.15 Replication and Fractional Seconds Support</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-invoked">17.5.1.16 Replication of Invoked Features</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-json">17.5.1.17 Replication of JSON Documents</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-limit">17.5.1.18 Replication and LIMIT</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-load-data">17.5.1.19 Replication and LOAD DATA</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-max-allowed-packet">17.5.1.20 Replication and max_allowed_packet</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-memory">17.5.1.21 Replication and MEMORY Tables</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-mysqldb">17.5.1.22 Replication of the mysql System Schema</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-optimizer">17.5.1.23 Replication and the Query Optimizer</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-partitioning">17.5.1.24 Replication and Partitioning</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-repair-table">17.5.1.25 Replication and REPAIR TABLE</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-reserved-words">17.5.1.26 Replication and Reserved Words</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-shutdowns">17.5.1.27 Replication and Master or Slave Shutdowns</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-slaveerrors">17.5.1.28 Slave Errors During Replication</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-sql-mode">17.5.1.29 Replication and Server SQL Mode</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-temptables">17.5.1.30 Replication and Temporary Tables</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-timeout">17.5.1.31 Replication Retries and Timeouts</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-timezone">17.5.1.32 Replication and Time Zones</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-transaction-inconsistencies">17.5.1.33 Replication and Transaction Inconsistencies</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-transactions">17.5.1.34 Replication and Transactions</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-triggers">17.5.1.35 Replication and Triggers</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-truncate">17.5.1.36 Replication and TRUNCATE TABLE</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-user-names">17.5.1.37 Replication and User Name Length</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-variables">17.5.1.38 Replication and Variables</a></span></dt><dt><span class="section"><a href="replication.html#replication-features-views">17.5.1.39 Replication and Views</a></span></dt></dl>
</div>
<a class="indexterm" name="idm46444261719440"></a><a class="indexterm" name="idm46444261718048"></a><a class="indexterm" name="idm46444261717040"></a><a class="indexterm" name="idm46444261715648"></a><a class="indexterm" name="idm46444261714640"></a><a class="indexterm" name="idm46444261713632"></a><p>
      The following sections provide information about what is supported
      and what is not in MySQL replication, and about specific issues
      and situations that may occur when replicating certain statements.
    </p><p>
      Statement-based replication depends on compatibility at the SQL
      level between the master and slave. In other words, successful
      statement-based replication requires that any SQL features used be
      supported by both the master and the slave servers. If you use a
      feature on the master server that is available only in the current
      version of MySQL, you cannot replicate to a slave that uses an
      earlier version of MySQL. Such incompatibilities can also occur
      within a release series as well as between versions.
    </p><p>
      If you are planning to use statement-based replication between
      MySQL 8.0 and a previous MySQL release series, it is
      a good idea to consult the edition of the <em class="citetitle">MySQL
      Reference Manual</em> corresponding to the earlier release
      series for information regarding the replication characteristics
      of that series.
    </p><p>
      With MySQL's statement-based replication, there may be issues with
      replicating stored routines or triggers. You can avoid these
      issues by using MySQL's row-based replication instead. For a
      detailed list of issues, see
      <a class="xref" href="stored-objects.html#stored-programs-logging" title="24.7 Stored Program Binary Logging">Section 24.7, “Stored Program Binary Logging”</a>. For more information
      about row-based logging and row-based replication, see
      <a class="xref" href="server-administration.html#binary-log-formats" title="5.4.4.1 Binary Logging Formats">Section 5.4.4.1, “Binary Logging Formats”</a>, and
      <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
    </p><p>
      For additional information specific to replication and
      <code class="literal">InnoDB</code>, see
      <a class="xref" href="innodb-storage-engine.html#innodb-and-mysql-replication" title="15.19 InnoDB and MySQL Replication">Section 15.19, “InnoDB and MySQL Replication”</a>. For information
      relating to replication with NDB Cluster, see
      <a class="xref" href="mysql-cluster.html#mysql-cluster-replication" title="22.6 NDB Cluster Replication">Section 22.6, “NDB Cluster Replication”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-auto-increment"></a>17.5.1.1 Replication and AUTO_INCREMENT</h4>
</div>
</div>
</div>
<a class="indexterm" name="idm46444261704240"></a><a class="indexterm" name="idm46444261702848"></a><a class="indexterm" name="idm46444261701456"></a><a class="indexterm" name="idm46444261700064"></a><a class="indexterm" name="idm46444261698672"></a><a class="indexterm" name="idm46444261697280"></a><p>
        Statement-based replication of
        <code class="literal">AUTO_INCREMENT</code>,
        <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>, and
        <a class="link" href="data-types.html#datetime" title="11.2.2 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values is carried out
        subject to the following exceptions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A statement invoking a trigger or function that causes an
            update to an <code class="literal">AUTO_INCREMENT</code> column is not
            replicated correctly using statement-based replication.
            These statements are marked as unsafe. (Bug #45677)
          </p></li><li class="listitem"><p>
            An <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> into a table that
            has a composite primary key that includes an
            <code class="literal">AUTO_INCREMENT</code> column that is not the
            first column of this composite key is not safe for
            statement-based logging or replication. These statements are
            marked as unsafe. (Bug #11754117, Bug #45670)
          </p><p>
            This issue does not affect tables using the
            <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> storage engine, since an
            <code class="literal">InnoDB</code> table with an
            <a class="link" href="glossary.html#glos_auto_increment" title="auto-increment">AUTO_INCREMENT</a>
            column requires at least one key where the auto-increment
            column is the only or leftmost column.
          </p></li><li class="listitem"><p>
            Adding an <code class="literal">AUTO_INCREMENT</code> column to a
            table with <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a> might
            not produce the same ordering of the rows on the slave and
            the master. This occurs because the order in which the rows
            are numbered depends on the specific storage engine used for
            the table and the order in which the rows were inserted. If
            it is important to have the same order on the master and
            slave, the rows must be ordered before assigning an
            <code class="literal">AUTO_INCREMENT</code> number. Assuming that you
            want to add an <code class="literal">AUTO_INCREMENT</code> column to a
            table <code class="literal">t1</code> that has columns
            <code class="literal">col1</code> and <code class="literal">col2</code>, the
            following statements produce a new table
            <code class="literal">t2</code> identical to <code class="literal">t1</code> but
            with an <code class="literal">AUTO_INCREMENT</code> column:
          </p><pre data-lang="sql" class="programlisting">CREATE TABLE t2 LIKE t1;
ALTER TABLE t2 ADD id INT AUTO_INCREMENT PRIMARY KEY;
INSERT INTO t2 SELECT * FROM t1 ORDER BY col1, col2;</pre>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
              To guarantee the same ordering on both master and slave,
              the <code class="literal">ORDER BY</code> clause must name
              <span class="emphasis"><em>all</em></span> columns of <code class="literal">t1</code>.
</p>
</div>
<p>
            The instructions just given are subject to the limitations
            of <a class="link" href="sql-statements.html#create-table-like" title="13.1.20.3 CREATE TABLE ... LIKE Statement"><code class="literal">CREATE
            TABLE ... LIKE</code></a>: Foreign key definitions are
            ignored, as are the <code class="literal">DATA DIRECTORY</code> and
            <code class="literal">INDEX DIRECTORY</code> table options. If a table
            definition includes any of those characteristics, create
            <code class="literal">t2</code> using a <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
            TABLE</code></a> statement that is identical to the one used
            to create <code class="literal">t1</code>, but with the addition of
            the <code class="literal">AUTO_INCREMENT</code> column.
          </p><p>
            Regardless of the method used to create and populate the
            copy having the <code class="literal">AUTO_INCREMENT</code> column,
            the final step is to drop the original table and then rename
            the copy:
          </p><pre data-lang="sql" class="programlisting">DROP t1;
ALTER TABLE t2 RENAME t1;</pre><p>
            See also <a class="xref" href="error-handling.html#alter-table-problems" title="B.4.6.1 Problems with ALTER TABLE">Section B.4.6.1, “Problems with ALTER TABLE”</a>.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-blackhole"></a>17.5.1.2 Replication and BLACKHOLE Tables</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261663840"></a><a class="indexterm" name="idm46444261662448"></a><a class="indexterm" name="idm46444261661056"></a><a class="indexterm" name="idm46444261659664"></a><p>
        The <a class="link" href="storage-engines.html#blackhole-storage-engine" title="16.6 The BLACKHOLE Storage Engine"><code class="literal">BLACKHOLE</code></a> storage engine
        accepts data but discards it and does not store it. When
        performing binary logging, all inserts to such tables are always
        logged, regardless of the logging format in use. Updates and
        deletes are handled differently depending on whether statement
        based or row based logging is in use. With the statement based
        logging format, all statements affecting
        <code class="literal">BLACKHOLE</code> tables are logged, but their
        effects ignored. When using row-based logging, updates and
        deletes to such tables are simply skipped—they are not
        written to the binary log. A warning is logged whenever this
        occurs.
      </p><p>
        For this reason we recommend when you replicate to tables using
        the <a class="link" href="storage-engines.html#blackhole-storage-engine" title="16.6 The BLACKHOLE Storage Engine"><code class="literal">BLACKHOLE</code></a> storage engine that
        you have the <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>
        server variable set to <code class="literal">STATEMENT</code>, and not to
        either <code class="literal">ROW</code> or <code class="literal">MIXED</code>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-charset"></a>17.5.1.3 Replication and Character Sets</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261649968"></a><a class="indexterm" name="idm46444261648576"></a><p>
        The following applies to replication between MySQL servers that
        use different character sets:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If the master has databases with a character set different
            from the global
            <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a> value,
            you should design your <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
            TABLE</code></a> statements so that they do not implicitly
            rely on the database default character set. A good
            workaround is to state the character set and collation
            explicitly in <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a>
            statements.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-checksum-table"></a>17.5.1.4 Replication and CHECKSUM TABLE</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261641200"></a><a class="indexterm" name="idm46444261639808"></a><p>
        <a class="link" href="sql-statements.html#checksum-table" title="13.7.3.3 CHECKSUM TABLE Statement"><code class="literal">CHECKSUM TABLE</code></a> returns a checksum
        that is calculated row by row, using a method that depends on
        the table row storage format. The storage format is not
        guaranteed to remain the same between MySQL versions, so the
        checksum value might change following an upgrade.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-create-alter-drop-server"></a>17.5.1.5 Replication of CREATE SERVER, ALTER SERVER, and DROP SERVER</h4>

</div>

</div>

</div>
<p>
        The statements <a class="link" href="sql-statements.html#create-server" title="13.1.18 CREATE SERVER Statement"><code class="literal">CREATE SERVER</code></a>,
        <a class="link" href="sql-statements.html#alter-server" title="13.1.8 ALTER SERVER Statement"><code class="literal">ALTER SERVER</code></a>, and
        <a class="link" href="sql-statements.html#drop-server" title="13.1.30 DROP SERVER Statement"><code class="literal">DROP SERVER</code></a> are not written to
        the binary log, regardless of the binary logging format that is
        in use.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-create-if-not-exists"></a>17.5.1.6 Replication of CREATE ... IF NOT EXISTS Statements</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261631152"></a><a class="indexterm" name="idm46444261629760"></a><p>
        MySQL applies these rules when various <code class="literal">CREATE ... IF
        NOT EXISTS</code> statements are replicated:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Every
            <a class="link" href="sql-statements.html#create-database" title="13.1.12 CREATE DATABASE Statement"><code class="literal">CREATE
            DATABASE IF NOT EXISTS</code></a> statement is replicated,
            whether or not the database already exists on the master.
          </p></li><li class="listitem"><p>
            Similarly, every
            <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE
            IF NOT EXISTS</code></a> statement without a
            <a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT</code></a> is replicated, whether
            or not the table already exists on the master. This includes
            <a class="link" href="sql-statements.html#create-table-like" title="13.1.20.3 CREATE TABLE ... LIKE Statement"><code class="literal">CREATE
            TABLE IF NOT EXISTS ... LIKE</code></a>. Replication of
            <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
            TABLE IF NOT EXISTS ... SELECT</code></a> follows somewhat
            different rules; see
            <a class="xref" href="replication.html#replication-features-create-select" title="17.5.1.7 Replication of CREATE TABLE ... SELECT Statements">Section 17.5.1.7, “Replication of CREATE TABLE ... SELECT Statements”</a>, for
            more information.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-event" title="13.1.13 CREATE EVENT Statement"><code class="literal">CREATE EVENT
            IF NOT EXISTS</code></a> is always replicated, whether or not
            the event named in the statement already exists on the
            master.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-create-select"></a>17.5.1.7 Replication of CREATE TABLE ... SELECT Statements</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261616736"></a><a class="indexterm" name="idm46444261615344"></a><p>
        MySQL applies these rules when
        <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
        TABLE ... SELECT</code></a> statements are replicated:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
            TABLE ... SELECT</code></a> always performs an implicit
            commit (<a class="xref" href="sql-statements.html#implicit-commit" title="13.3.3 Statements That Cause an Implicit Commit">Section 13.3.3, “Statements That Cause an Implicit Commit”</a>).
          </p></li><li class="listitem"><p>
            If the destination table does not exist, logging occurs as
            follows. It does not matter whether <code class="literal">IF NOT
            EXISTS</code> is present.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">STATEMENT</code> or <code class="literal">MIXED</code>
                format: The statement is logged as written.
              </p></li><li class="listitem"><p>
                <code class="literal">ROW</code> format: The statement is logged
                as a <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a>
                statement followed by a series of insert-row events.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            If the
            <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
            TABLE ... SELECT</code></a> statement fails, nothing is
            logged. This includes the case that the destination table
            exists and <code class="literal">IF NOT EXISTS</code> is not given.
          </p></li><li class="listitem"><p>
            If the destination table exists and <code class="literal">IF NOT
            EXISTS</code> is given, MySQL 8.0 ignores
            the statement completely; nothing is inserted or logged.
</p></li></ul>
</div>
<p>
        When statement-based replication is in use, MySQL
        8.0 does not allow a
        <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
        TABLE ... SELECT</code></a> statement to make any changes in
        tables other than the table that is created by the statement.
        This is not an issue when using row-based replication, because
        the statement is logged as a <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE
        TABLE</code></a> statement with any changes to table data logged
        as row-insert events, rather than as the entire
        <a class="link" href="sql-statements.html#create-table-select" title="13.1.20.4 CREATE TABLE ... SELECT Statement"><code class="literal">CREATE
        TABLE ... SELECT</code></a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-current-user"></a>17.5.1.8 Replication of CURRENT_USER()</h4>

</div>

</div>

</div>
<p>
        The following statements support use of the
        <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER()</code></a> function to take
        the place of the name of, and possibly the host for, an affected
        user or a definer:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="sql-statements.html#drop-user" title="13.7.1.5 DROP USER Statement"><code class="literal">DROP USER</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#rename-user" title="13.7.1.7 RENAME USER Statement"><code class="literal">RENAME USER</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#revoke" title="13.7.1.8 REVOKE Statement"><code class="literal">REVOKE</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-function" title="13.1.14 CREATE FUNCTION Statement"><code class="literal">CREATE FUNCTION</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-procedure" title="13.1.17 CREATE PROCEDURE and CREATE FUNCTION Statements"><code class="literal">CREATE PROCEDURE</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-trigger" title="13.1.22 CREATE TRIGGER Statement"><code class="literal">CREATE TRIGGER</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-event" title="13.1.13 CREATE EVENT Statement"><code class="literal">CREATE EVENT</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#create-view" title="13.1.23 CREATE VIEW Statement"><code class="literal">CREATE VIEW</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#alter-view" title="13.1.11 ALTER VIEW Statement"><code class="literal">ALTER VIEW</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#set-password" title="13.7.1.10 SET PASSWORD Statement"><code class="literal">SET PASSWORD</code></a>
</p></li></ul>
</div>
<p>
        When binary logging is enabled and
        <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER()</code></a> or
        <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER</code></a> is used as the
        definer in any of these statements, MySQL Server ensures that
        the statement is applied to the same user on both the master and
        the slave when the statement is replicated. In some cases, such
        as statements that change passwords, the function reference is
        expanded before it is written to the binary log, so that the
        statement includes the user name. For all other cases, the name
        of the current user on the master is replicated to the slave as
        metadata, and the slave applies the statement to the current
        user named in the metadata, rather than to the current user on
        the slave.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-differing-tables"></a>17.5.1.9 Replication with Differing Table Definitions on Master and Slave</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261567280"></a><p>
        Source and target tables for replication do not have to be
        identical. A table on the master can have more or fewer columns
        than the slave's copy of the table. In addition, corresponding
        table columns on the master and the slave can use different data
        types, subject to certain conditions.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          Replication between tables which are partitioned differently
          from one another is not supported. See
          <a class="xref" href="replication.html#replication-features-partitioning" title="17.5.1.24 Replication and Partitioning">Section 17.5.1.24, “Replication and Partitioning”</a>.
</p>
</div>
<p>
        In all cases where the source and target tables do not have
        identical definitions, the database and table names must be the
        same on both the master and the slave. Additional conditions are
        discussed, with examples, in the following two sections.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-features-more-columns"></a>17.5.1.9.1 Replication with More Columns on Master or Slave</h5>
</div>
</div>
</div>
<p>
          You can replicate a table from the master to the slave such
          that the master and slave copies of the table have differing
          numbers of columns, subject to the following conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Columns common to both versions of the table must be
              defined in the same order on the master and the slave.
            </p><p>
              (This is true even if both tables have the same number of
              columns.)
            </p></li><li class="listitem"><p>
              Columns common to both versions of the table must be
              defined before any additional columns.
            </p><p>
              This means that executing an <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
              TABLE</code></a> statement on the slave where a new column
              is inserted into the table within the range of columns
              common to both tables causes replication to fail, as shown
              in the following example:
            </p><p>
              Suppose that a table <code class="literal">t</code>, existing on the
              master and the slave, is defined by the following
              <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a> statement:
            </p><pre data-lang="sql" class="programlisting">CREATE TABLE t (
    c1 INT,
    c2 INT,
    c3 INT
);</pre><p>
              Suppose that the <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
              TABLE</code></a> statement shown here is executed on the
              slave:
            </p><pre data-lang="sql" class="programlisting">ALTER TABLE t ADD COLUMN cnew1 INT AFTER c3;</pre><p>
              The previous <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a> is
              permitted on the slave because the columns
              <code class="literal">c1</code>, <code class="literal">c2</code>, and
              <code class="literal">c3</code> that are common to both versions of
              table <code class="literal">t</code> remain grouped together in both
              versions of the table, before any columns that differ.
            </p><p>
              However, the following <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER
              TABLE</code></a> statement cannot be executed on the slave
              without causing replication to break:
            </p><pre data-lang="sql" class="programlisting">ALTER TABLE t ADD COLUMN cnew2 INT AFTER c2;</pre><p>
              Replication fails after execution on the slave of the
              <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a> statement just
              shown, because the new column <code class="literal">cnew2</code>
              comes between columns common to both versions of
              <code class="literal">t</code>.
            </p></li><li class="listitem"><p>
              Each <span class="quote">“<span class="quote">extra</span>”</span> column in the version of the
              table having more columns must have a default value.
            </p><p>
              A column's default value is determined by a number of
              factors, including its type, whether it is defined with a
              <code class="literal">DEFAULT</code> option, whether it is declared
              as <code class="literal">NULL</code>, and the server SQL mode in
              effect at the time of its creation; for more information,
              see <a class="xref" href="data-types.html#data-type-defaults" title="11.6 Data Type Default Values">Section 11.6, “Data Type Default Values”</a>).
</p></li></ul>
</div>
<p>
          In addition, when the slave's copy of the table has more
          columns than the master's copy, each column common to the
          tables must use the same data type in both tables.
        </p><p><b>Examples. </b>
            The following examples illustrate some valid and invalid
            table definitions:
          </p><p><b>More columns on the master. </b>
            The following table definitions are valid and replicate
            correctly:
          </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT);</code></strong>
</pre><p>
          The following table definitions would raise an error because
          the definitions of the columns common to both versions of the
          table are in a different order on the slave than they are on
          the master:
        </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c2 INT, c1 INT);</code></strong>
</pre><p>
          The following table definitions would also raise an error
          because the definition of the extra column on the master
          appears before the definitions of the columns common to both
          versions of the table:
        </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c3 INT, c1 INT, c2 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT);</code></strong>
</pre><p><b>More columns on the slave. </b>
            The following table definitions are valid and replicate
            correctly:
          </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);</code></strong>
                  </pre><p>
          The following definitions raise an error because the columns
          common to both versions of the table are not defined in the
          same order on both the master and the slave:
        </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c2 INT, c1 INT, c3 INT);</code></strong>
</pre><p>
          The following table definitions also raise an error because
          the definition for the extra column in the slave's version of
          the table appears before the definitions for the columns which
          are common to both versions of the table:
        </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c3 INT, c1 INT, c2 INT);</code></strong>
</pre><p>
          The following table definitions fail because the slave's
          version of the table has additional columns compared to the
          master's version, and the two versions of the table use
          different data types for the common column
          <code class="literal">c2</code>:
        </p><pre data-lang="sql" class="programlisting">master&gt; <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 BIGINT);</code></strong>
slave&gt;  <strong class="userinput"><code>CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="replication-features-different-data-types"></a>17.5.1.9.2 Replication of Columns Having Different Data Types</h5>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261514640"></a><a class="indexterm" name="idm46444261513248"></a><a class="indexterm" name="idm46444261511856"></a><a class="indexterm" name="idm46444261510464"></a><p>
          Corresponding columns on the master's and the
          slave's copies of the same table ideally should have the
          same data type. However, this is not always strictly enforced,
          as long as certain conditions are met.
        </p><p>
          It is usually possible to replicate from a column of a given
          data type to another column of the same type and same size or
          width, where applicable, or larger. For example, you can
          replicate from a <code class="literal">CHAR(10)</code> column to another
          <code class="literal">CHAR(10)</code>, or from a
          <code class="literal">CHAR(10)</code> column to a
          <code class="literal">CHAR(25)</code> column without any problems. In
          certain cases, it also possible to replicate from a column
          having one data type (on the master) to a column having a
          different data type (on the slave); when the data type of the
          master's version of the column is promoted to a type that
          is the same size or larger on the slave, this is known as
          <span class="firstterm">attribute promotion</span>.
        </p><p>
          Attribute promotion can be used with both statement-based and
          row-based replication, and is not dependent on the storage
          engine used by either the master or the slave. However, the
          choice of logging format does have an effect on the type
          conversions that are permitted; the particulars are discussed
          later in this section.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
            Whether you use statement-based or row-based replication,
            the slave's copy of the table cannot contain more
            columns than the master's copy if you wish to employ
            attribute promotion.
</p>
</div>
<p><b>Statement-based replication. </b>
            When using statement-based replication, a simple rule of
            thumb to follow is, <span class="quote">“<span class="quote">If the statement run on the
            master would also execute successfully on the slave, it
            should also replicate successfully</span>”</span>. In other words,
            if the statement uses a value that is compatible with the
            type of a given column on the slave, the statement can be
            replicated. For example, you can insert any value that fits
            in a <code class="literal">TINYINT</code> column into a
            <code class="literal">BIGINT</code> column as well; it follows that,
            even if you change the type of a <code class="literal">TINYINT</code>
            column in the slave's copy of a table to
            <code class="literal">BIGINT</code>, any insert into that column on
            the master that succeeds should also succeed on the slave,
            since it is impossible to have a legal
            <code class="literal">TINYINT</code> value that is large enough to
            exceed a <code class="literal">BIGINT</code> column.
          </p><p><a name="replication-features-attribute-promotion"></a><b>Row-based replication: attribute promotion and demotion. </b>
            Row-based replication supports attribute promotion and
            demotion between smaller data types and larger types. It is
            also possible to specify whether or not to permit lossy
            (truncated) or non-lossy conversions of demoted column
            values, as explained later in this section.
          </p><p><b>Lossy and non-lossy conversions. </b>
            In the event that the target type cannot represent the value
            being inserted, a decision must be made on how to handle the
            conversion. If we permit the conversion but truncate (or
            otherwise modify) the source value to achieve a
            <span class="quote">“<span class="quote">fit</span>”</span> in the target column, we make what is
            known as a <span class="firstterm">lossy
            conversion</span>. A conversion which does not require
            truncation or similar modifications to fit the source column
            value in the target column is a
            <span class="firstterm">non-lossy</span> conversion.
          </p><p><b>Type conversion modes (slave_type_conversions variable). </b>
            The setting of the <code class="literal">slave_type_conversions</code>
            global server variable controls the type conversion mode
            used on the slave. This variable takes a set of values from
            the following list, which describes the effects of each mode
            on the slave's type-conversion behavior:
</p>
<div class="variablelist">
<dl class="variablelist"><dt><span class="term">
              ALL_LOSSY
            </span></dt><dd><p>
                In this mode, type conversions that would mean loss of
                information are permitted.
              </p><p>
                This does not imply that non-lossy conversions are
                permitted, merely that only cases requiring either lossy
                conversions or no conversion at all are permitted; for
                example, enabling <span class="emphasis"><em>only</em></span> this mode
                permits an <code class="literal">INT</code> column to be converted
                to <code class="literal">TINYINT</code> (a lossy conversion), but
                not a <code class="literal">TINYINT</code> column to an
                <code class="literal">INT</code> column (non-lossy). Attempting
                the latter conversion in this case would cause
                replication to stop with an error on the slave.
              </p></dd><dt><span class="term">
              ALL_NON_LOSSY
            </span></dt><dd><p>
                This mode permits conversions that do not require
                truncation or other special handling of the source
                value; that is, it permits conversions where the target
                type has a wider range than the source type.
              </p><p>
                Setting this mode has no bearing on whether lossy
                conversions are permitted; this is controlled with the
                <code class="literal">ALL_LOSSY</code> mode. If only
                <code class="literal">ALL_NON_LOSSY</code> is set, but not
                <code class="literal">ALL_LOSSY</code>, then attempting a
                conversion that would result in the loss of data (such
                as <code class="literal">INT</code> to <code class="literal">TINYINT</code>,
                or <code class="literal">CHAR(25)</code> to
                <code class="literal">VARCHAR(20)</code>) causes the slave to stop
                with an error.
              </p></dd><dt><span class="term">
              ALL_LOSSY,ALL_NON_LOSSY
            </span></dt><dd><p>
                When this mode is set, all supported type conversions
                are permitted, whether or not they are lossy
                conversions.
              </p></dd><dt><span class="term">
              ALL_SIGNED
            </span></dt><dd><p>
                Treat promoted integer types as signed values (the
                default behavior).
              </p></dd><dt><span class="term">
              ALL_UNSIGNED
            </span></dt><dd><p>
                Treat promoted integer types as unsigned values.
              </p></dd><dt><span class="term">
              ALL_SIGNED,ALL_UNSIGNED
            </span></dt><dd><p>
                Treat promoted integer types as signed if possible,
                otherwise as unsigned.
              </p></dd><dt><span class="term">
              [<span class="emphasis"><em>empty</em></span>]
            </span></dt><dd><p>
                When <code class="literal">slave_type_conversions</code> is not
                set, no attribute promotion or demotion is permitted;
                this means that all columns in the source and target
                tables must be of the same types.
              </p><p>
                This mode is the default.
</p></dd></dl>
</div>
<p>
          When an integer type is promoted, its signedness is not
          preserved. By default, the slave treats all such values as
          signed. You can control this behavior using
          <code class="literal">ALL_SIGNED</code>,
          <code class="literal">ALL_UNSIGNED</code>, or both.
          <code class="literal">ALL_SIGNED</code> tells the slave to treat all
          promoted integer types as signed;
          <code class="literal">ALL_UNSIGNED</code> instructs it to treat these as
          unsigned. Specifying both causes the slave to treat the value
          as signed if possible, otherwise to treat it as unsigned; the
          order in which they are listed is not significant. Neither
          <code class="literal">ALL_SIGNED</code> nor
          <code class="literal">ALL_UNSIGNED</code> has any effect if at least one
          of <code class="literal">ALL_LOSSY</code> or
          <code class="literal">ALL_NONLOSSY</code> is not also used.
        </p><p>
          Changing the type conversion mode requires restarting the
          slave with the new <code class="literal">slave_type_conversions</code>
          setting.
        </p><p><b>Supported conversions. </b>
            Supported conversions between different but similar data
            types are shown in the following list:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Between any of the integer types
              <a class="link" href="data-types.html#integer-types" title="11.1.2 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">TINYINT</code></a>,
              <a class="link" href="data-types.html#integer-types" title="11.1.2 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">SMALLINT</code></a>,
              <a class="link" href="data-types.html#integer-types" title="11.1.2 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">MEDIUMINT</code></a>,
              <a class="link" href="data-types.html#integer-types" title="11.1.2 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">INT</code></a>, and
              <a class="link" href="data-types.html#integer-types" title="11.1.2 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT"><code class="literal">BIGINT</code></a>.
            </p><p>
              This includes conversions between the signed and unsigned
              versions of these types.
            </p><p>
              Lossy conversions are made by truncating the source value
              to the maximum (or minimum) permitted by the target
              column. For ensuring non-lossy conversions when going from
              unsigned to signed types, the target column must be large
              enough to accommodate the range of values in the source
              column. For example, you can demote <code class="literal">TINYINT
              UNSIGNED</code> non-lossily to
              <code class="literal">SMALLINT</code>, but not to
              <code class="literal">TINYINT</code>.
            </p></li><li class="listitem"><p>
              Between any of the decimal types
              <a class="link" href="data-types.html#fixed-point-types" title="11.1.3 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">DECIMAL</code></a>,
              <a class="link" href="data-types.html#floating-point-types" title="11.1.4 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">FLOAT</code></a>,
              <a class="link" href="data-types.html#floating-point-types" title="11.1.4 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE"><code class="literal">DOUBLE</code></a>, and
              <a class="link" href="data-types.html#fixed-point-types" title="11.1.3 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC"><code class="literal">NUMERIC</code></a>.
            </p><p>
              <code class="literal">FLOAT</code> to <code class="literal">DOUBLE</code> is a
              non-lossy conversion; <code class="literal">DOUBLE</code> to
              <code class="literal">FLOAT</code> can only be handled lossily. A
              conversion from
              <code class="literal">DECIMAL(<em class="replaceable"><code>M</code></em>,<em class="replaceable"><code>D</code></em>)</code>
              to
              <code class="literal">DECIMAL(<em class="replaceable"><code>M'</code></em>,<em class="replaceable"><code>D'</code></em>)</code>
              where <code class="literal"><em class="replaceable"><code>D'</code></em> &gt;=
              <em class="replaceable"><code>D</code></em></code> and
              <code class="literal">(<em class="replaceable"><code>M'</code></em>-<em class="replaceable"><code>D'</code></em>)
              &gt;=
              (<em class="replaceable"><code>M</code></em>-<em class="replaceable"><code>D</code></em></code>)
              is non-lossy; for any case where
              <code class="literal"><em class="replaceable"><code>M'</code></em> &lt;
              <em class="replaceable"><code>M</code></em></code>,
              <code class="literal"><em class="replaceable"><code>D'</code></em> &lt;
              <em class="replaceable"><code>D</code></em></code>, or both, only a
              lossy conversion can be made.
            </p><p>
              For any of the decimal types, if a value to be stored
              cannot be fit in the target type, the value is rounded
              down according to the rounding rules defined for the
              server elsewhere in the documentation. See
              <a class="xref" href="functions.html#precision-math-rounding" title="12.25.4 Rounding Behavior">Section 12.25.4, “Rounding Behavior”</a>, for information
              about how this is done for decimal types.
            </p></li><li class="listitem"><p>
              Between any of the string types
              <a class="link" href="data-types.html#char" title="11.3.2 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
              <a class="link" href="data-types.html#char" title="11.3.2 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and
              <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">TEXT</code></a>, including conversions
              between different widths.
            </p><p>
              Conversion of a <code class="literal">CHAR</code>,
              <code class="literal">VARCHAR</code>, or <code class="literal">TEXT</code> to
              a <code class="literal">CHAR</code>, <code class="literal">VARCHAR</code>, or
              <code class="literal">TEXT</code> column the same size or larger is
              never lossy. Lossy conversion is handled by inserting only
              the first <em class="replaceable"><code>N</code></em> characters of the
              string on the slave, where <em class="replaceable"><code>N</code></em> is
              the width of the target column.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
                Replication between columns using different character
                sets is not supported.
</p>
</div>
</li><li class="listitem"><p>
              Between any of the binary data types
              <a class="link" href="data-types.html#binary-varbinary" title="11.3.3 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a>,
              <a class="link" href="data-types.html#binary-varbinary" title="11.3.3 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a>, and
              <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">BLOB</code></a>, including conversions
              between different widths.
            </p><p>
              Conversion of a <code class="literal">BINARY</code>,
              <code class="literal">VARBINARY</code>, or <code class="literal">BLOB</code>
              to a <code class="literal">BINARY</code>,
              <code class="literal">VARBINARY</code>, or <code class="literal">BLOB</code>
              column the same size or larger is never lossy. Lossy
              conversion is handled by inserting only the first
              <em class="replaceable"><code>N</code></em> bytes of the string on the
              slave, where <em class="replaceable"><code>N</code></em> is the width of
              the target column.
            </p></li><li class="listitem"><p>
              Between any 2 <a class="link" href="data-types.html#bit-type" title="11.1.5 Bit-Value Type - BIT"><code class="literal">BIT</code></a> columns
              of any 2 sizes.
            </p><p>
              When inserting a value from a
              <code class="literal">BIT(<em class="replaceable"><code>M</code></em>)</code>
              column into a
              <code class="literal">BIT(<em class="replaceable"><code>M'</code></em>)</code>
              column, where <code class="literal"><em class="replaceable"><code>M'</code></em> &gt;
              <em class="replaceable"><code>M</code></em></code>, the most
              significant bits of the
              <code class="literal">BIT(<em class="replaceable"><code>M'</code></em>)</code>
              columns are cleared (set to zero) and the
              <em class="replaceable"><code>M</code></em> bits of the
              <code class="literal">BIT(<em class="replaceable"><code>M</code></em>)</code> value
              are set as the least significant bits of the
              <code class="literal">BIT(<em class="replaceable"><code>M'</code></em>)</code>
              column.
            </p><p>
              When inserting a value from a source
              <code class="literal">BIT(<em class="replaceable"><code>M</code></em>)</code>
              column into a target
              <code class="literal">BIT(<em class="replaceable"><code>M'</code></em>)</code>
              column, where <code class="literal"><em class="replaceable"><code>M'</code></em> &lt;
              <em class="replaceable"><code>M</code></em></code>, the maximum
              possible value for the
              <code class="literal">BIT(<em class="replaceable"><code>M'</code></em>)</code>
              column is assigned; in other words, an
              <span class="quote">“<span class="quote">all-set</span>”</span> value is assigned to the target
              column.
</p></li></ul>
</div>
<p>
          Conversions between types not in the previous list are not
          permitted.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-directory"></a>17.5.1.10 Replication and DIRECTORY Table Options</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261396176"></a><a class="indexterm" name="idm46444261394784"></a><a class="indexterm" name="idm46444261393392"></a><a class="indexterm" name="idm46444261392000"></a><a class="indexterm" name="idm46444261390608"></a><p>
        If a <code class="literal">DATA DIRECTORY</code> or <code class="literal">INDEX
        DIRECTORY</code> table option is used in a
        <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a> statement on the
        master server, the table option is also used on the slave. This
        can cause problems if no corresponding directory exists in the
        slave host file system or if it exists but is not accessible to
        the slave server. This can be overridden by using the
        <a class="link" href="server-administration.html#sqlmode_no_dir_in_create"><code class="literal">NO_DIR_IN_CREATE</code></a> server SQL
        mode on the slave, which causes the slave to ignore the
        <code class="literal">DATA DIRECTORY</code> and <code class="literal">INDEX
        DIRECTORY</code> table options when replicating
        <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a> statements. The
        result is that <code class="literal">MyISAM</code> data and index files
        are created in the table's database directory.
      </p><p>
        For more information, see <a class="xref" href="server-administration.html#sql-mode" title="5.1.11 Server SQL Modes">Section 5.1.11, “Server SQL Modes”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-drop-if-exists"></a>17.5.1.11 Replication of DROP ... IF EXISTS Statements</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261379952"></a><a class="indexterm" name="idm46444261378560"></a><p>
        The <a class="link" href="sql-statements.html#drop-database" title="13.1.24 DROP DATABASE Statement"><code class="literal">DROP DATABASE
        IF EXISTS</code></a>,
        <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TABLE IF
        EXISTS</code></a>, and
        <a class="link" href="sql-statements.html#drop-view" title="13.1.35 DROP VIEW Statement"><code class="literal">DROP VIEW IF
        EXISTS</code></a> statements are always replicated, even if the
        database, table, or view to be dropped does not exist on the
        master. This is to ensure that the object to be dropped no
        longer exists on either the master or the slave, once the slave
        has caught up with the master.
      </p><p>
        <code class="literal">DROP ... IF EXISTS</code> statements for stored
        programs (stored procedures and functions, triggers, and events)
        are also replicated, even if the stored program to be dropped
        does not exist on the master.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-floatvalues"></a>17.5.1.12 Replication and Floating-Point Values</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261371248"></a><a class="indexterm" name="idm46444261369856"></a><p>
        With statement-based replication, values are converted from
        decimal to binary. Because conversions between decimal and
        binary representations of them may be approximate, comparisons
        involving floating-point values are inexact. This is true for
        operations that use floating-point values explicitly, or that
        use values that are converted to floating-point implicitly.
        Comparisons of floating-point values might yield different
        results on master and slave servers due to differences in
        computer architecture, the compiler used to build MySQL, and so
        forth. See <a class="xref" href="functions.html#type-conversion" title="12.2 Type Conversion in Expression Evaluation">Section 12.2, “Type Conversion in Expression Evaluation”</a>, and
        <a class="xref" href="error-handling.html#problems-with-float" title="B.4.4.8 Problems with Floating-Point Values">Section B.4.4.8, “Problems with Floating-Point Values”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-flush"></a>17.5.1.13 Replication and FLUSH</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261365424"></a><a class="indexterm" name="idm46444261364032"></a><p>
        Some forms of the <a class="link" href="sql-statements.html#flush" title="13.7.8.3 FLUSH Statement"><code class="literal">FLUSH</code></a> statement
        are not logged because they could cause problems if replicated
        to a slave: <a class="link" href="sql-statements.html#flush-logs"><code class="literal">FLUSH LOGS</code></a> and
        <a class="link" href="sql-statements.html#flush-tables-with-read-lock"><code class="literal">FLUSH TABLES WITH READ LOCK</code></a>. For
        a syntax example, see <a class="xref" href="sql-statements.html#flush" title="13.7.8.3 FLUSH Statement">Section 13.7.8.3, “FLUSH Statement”</a>. The
        <a class="link" href="sql-statements.html#flush-tables"><code class="literal">FLUSH TABLES</code></a>,
        <a class="link" href="sql-statements.html#analyze-table" title="13.7.3.1 ANALYZE TABLE Statement"><code class="literal">ANALYZE TABLE</code></a>,
        <a class="link" href="sql-statements.html#optimize-table" title="13.7.3.4 OPTIMIZE TABLE Statement"><code class="literal">OPTIMIZE TABLE</code></a>, and
        <a class="link" href="sql-statements.html#repair-table" title="13.7.3.5 REPAIR TABLE Statement"><code class="literal">REPAIR TABLE</code></a> statements are
        written to the binary log and thus replicated to slaves. This is
        not normally a problem because these statements do not modify
        table data.
      </p><p>
        However, this behavior can cause difficulties under certain
        circumstances. If you replicate the privilege tables in the
        <code class="literal">mysql</code> database and update those tables
        directly without using <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a>, you
        must issue a <a class="link" href="sql-statements.html#flush-privileges"><code class="literal">FLUSH PRIVILEGES</code></a> on
        the slaves to put the new privileges into effect. In addition,
        if you use <a class="link" href="sql-statements.html#flush-tables"><code class="literal">FLUSH TABLES</code></a> when
        renaming a <code class="literal">MyISAM</code> table that is part of a
        <code class="literal">MERGE</code> table, you must issue
        <a class="link" href="sql-statements.html#flush-tables"><code class="literal">FLUSH TABLES</code></a> manually on the
        slaves. These statements are written to the binary log unless
        you specify <code class="literal">NO_WRITE_TO_BINLOG</code> or its alias
        <code class="literal">LOCAL</code>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-functions"></a>17.5.1.14 Replication and System Functions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261345536"></a><a class="indexterm" name="idm46444261344144"></a><p>
        Certain functions do not replicate well under some conditions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a>,
            <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER()</code></a> (or
            <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER</code></a>),
            <a class="link" href="functions.html#function_uuid"><code class="literal">UUID()</code></a>,
            <a class="link" href="functions.html#function_version"><code class="literal">VERSION()</code></a>, and
            <a class="link" href="functions.html#function_load-file"><code class="literal">LOAD_FILE()</code></a> functions are
            replicated without change and thus do not work reliably on
            the slave unless row-based replication is enabled. (See
            <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.)
          </p><p>
            <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a> and
            <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER()</code></a> are
            automatically replicated using row-based replication when
            using <code class="literal">MIXED</code> mode, and generate a warning
            in <code class="literal">STATEMENT</code> mode. (See also
            <a class="xref" href="replication.html#replication-features-current-user" title="17.5.1.8 Replication of CURRENT_USER()">Section 17.5.1.8, “Replication of CURRENT_USER()”</a>.) This
            is also true for <a class="link" href="functions.html#function_version"><code class="literal">VERSION()</code></a>
            and <a class="link" href="functions.html#function_rand"><code class="literal">RAND()</code></a>.
          </p></li><li class="listitem"><p>
            For <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a>, the binary log
            includes the timestamp. This means that the value
            <span class="emphasis"><em>as returned by the call to this function on the
            master</em></span> is replicated to the slave. To avoid
            unexpected results when replicating between MySQL servers in
            different time zones, set the time zone on both master and
            slave. For more information, see
            <a class="xref" href="replication.html#replication-features-timezone" title="17.5.1.32 Replication and Time Zones">Section 17.5.1.32, “Replication and Time Zones”</a>.
          </p><p>
            To explain the potential problems when replicating between
            servers which are in different time zones, suppose that the
            master is located in New York, the slave is located in
            Stockholm, and both servers are using local time. Suppose
            further that, on the master, you create a table
            <code class="literal">mytable</code>, perform an
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statement on this
            table, and then select from the table, as shown here:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>CREATE TABLE mytable (mycol TEXT);</code></strong>
Query OK, 0 rows affected (0.06 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO mytable VALUES ( NOW() );</code></strong>
Query OK, 1 row affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT * FROM mytable;</code></strong>
+---------------------+
| mycol               |
+---------------------+
| 2009-09-01 12:00:00 |
+---------------------+
1 row in set (0.00 sec)
</pre><p>
            Local time in Stockholm is 6 hours later than in New York;
            so, if you issue <code class="literal">SELECT NOW()</code> on the
            slave at that exact same instant, the value
            <code class="literal">2009-09-01 18:00:00</code> is returned. For this
            reason, if you select from the slave's copy of
            <code class="literal">mytable</code> after the
            <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TABLE</code></a> and
            <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statements just shown
            have been replicated, you might expect
            <code class="literal">mycol</code> to contain the value
            <code class="literal">2009-09-01 18:00:00</code>. However, this is not
            the case; when you select from the slave's copy of
            <code class="literal">mytable</code>, you obtain exactly the same
            result as on the master:
          </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SELECT * FROM mytable;</code></strong>
+---------------------+
| mycol               |
+---------------------+
| 2009-09-01 12:00:00 |
+---------------------+
1 row in set (0.00 sec)
</pre><p>
            Unlike <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a>, the
            <a class="link" href="functions.html#function_sysdate"><code class="literal">SYSDATE()</code></a> function is not
            replication-safe because it is not affected by <code class="literal">SET
            TIMESTAMP</code> statements in the binary log and is
            nondeterministic if statement-based logging is used. This is
            not a problem if row-based logging is used.
          </p><p>
            An alternative is to use the
            <a class="link" href="server-administration.html#option_mysqld_sysdate-is-now"><code class="option">--sysdate-is-now</code></a> option to
            cause <a class="link" href="functions.html#function_sysdate"><code class="literal">SYSDATE()</code></a> to be an
            alias for <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a>. This must be
            done on the master and the slave to work correctly. In such
            cases, a warning is still issued by this function, but can
            safely be ignored as long as
            <a class="link" href="server-administration.html#option_mysqld_sysdate-is-now"><code class="option">--sysdate-is-now</code></a> is used on
            both the master and the slave.
          </p><p>
            <a class="link" href="functions.html#function_sysdate"><code class="literal">SYSDATE()</code></a> is automatically
            replicated using row-based replication when using
            <code class="literal">MIXED</code> mode, and generates a warning in
            <code class="literal">STATEMENT</code> mode.
          </p><p>
            See also <a class="xref" href="replication.html#replication-features-timezone" title="17.5.1.32 Replication and Time Zones">Section 17.5.1.32, “Replication and Time Zones”</a>.
          </p></li><li class="listitem"><p>
            <span class="emphasis"><em>The following restriction applies to
            statement-based replication only, not to row-based
            replication.</em></span> The
            <a class="link" href="functions.html#function_get-lock"><code class="literal">GET_LOCK()</code></a>,
            <a class="link" href="functions.html#function_release-lock"><code class="literal">RELEASE_LOCK()</code></a>,
            <a class="link" href="functions.html#function_is-free-lock"><code class="literal">IS_FREE_LOCK()</code></a>, and
            <a class="link" href="functions.html#function_is-used-lock"><code class="literal">IS_USED_LOCK()</code></a> functions that
            handle user-level locks are replicated without the slave
            knowing the concurrency context on the master. Therefore,
            these functions should not be used to insert into a master
            table because the content on the slave would differ. For
            example, do not issue a statement such as <code class="literal">INSERT
            INTO mytable VALUES(GET_LOCK(...))</code>.
          </p><p>
            These functions are automatically replicated using row-based
            replication when using <code class="literal">MIXED</code> mode, and
            generate a warning in <code class="literal">STATEMENT</code> mode.
</p></li></ul>
</div>
<p>
        As a workaround for the preceding limitations when
        statement-based replication is in effect, you can use the
        strategy of saving the problematic function result in a user
        variable and referring to the variable in a later statement. For
        example, the following single-row
        <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> is problematic due to the
        reference to the <a class="link" href="functions.html#function_uuid"><code class="literal">UUID()</code></a> function:
      </p><pre data-lang="sql" class="programlisting">INSERT INTO t VALUES(UUID());</pre><p>
        To work around the problem, do this instead:
      </p><pre data-lang="sql" class="programlisting">SET @my_uuid = UUID();
INSERT INTO t VALUES(@my_uuid);</pre><p>
        That sequence of statements replicates because the value of
        <code class="literal">@my_uuid</code> is stored in the binary log as a
        user-variable event prior to the
        <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statement and is available
        for use in the <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>.
      </p><p>
        The same idea applies to multiple-row inserts, but is more
        cumbersome to use. For a two-row insert, you can do this:
      </p><pre data-lang="sql" class="programlisting">SET @my_uuid1 = UUID(); @my_uuid2 = UUID();
INSERT INTO t VALUES(@my_uuid1),(@my_uuid2);</pre><p>
        However, if the number of rows is large or unknown, the
        workaround is difficult or impracticable. For example, you
        cannot convert the following statement to one in which a given
        individual user variable is associated with each row:
      </p><pre data-lang="sql" class="programlisting">INSERT INTO t2 SELECT UUID(), * FROM t1;</pre><p>
        Within a stored function, <a class="link" href="functions.html#function_rand"><code class="literal">RAND()</code></a>
        replicates correctly as long as it is invoked only once during
        the execution of the function. (You can consider the function
        execution timestamp and random number seed as implicit inputs
        that are identical on the master and slave.)
      </p><p>
        The <a class="link" href="functions.html#function_found-rows"><code class="literal">FOUND_ROWS()</code></a> and
        <a class="link" href="functions.html#function_row-count"><code class="literal">ROW_COUNT()</code></a> functions are not
        replicated reliably using statement-based replication. A
        workaround is to store the result of the function call in a user
        variable, and then use that in the
        <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statement. For example, if
        you wish to store the result in a table named
        <code class="literal">mytable</code>, you might normally do so like this:
      </p><pre data-lang="sql" class="programlisting">SELECT SQL_CALC_FOUND_ROWS FROM mytable LIMIT 1;
INSERT INTO mytable VALUES( FOUND_ROWS() );</pre><p>
        However, if you are replicating <code class="literal">mytable</code>, you
        should use <a class="link" href="sql-statements.html#select-into" title="13.2.10.1 SELECT ... INTO Statement"><code class="literal">SELECT
        ... INTO</code></a>, and then store the variable in the table,
        like this:
      </p><pre data-lang="sql" class="programlisting">SELECT SQL_CALC_FOUND_ROWS INTO @found_rows FROM mytable LIMIT 1;
INSERT INTO mytable VALUES(@found_rows);</pre><p>
        In this way, the user variable is replicated as part of the
        context, and applied on the slave correctly.
      </p><p>
        These functions are automatically replicated using row-based
        replication when using <code class="literal">MIXED</code> mode, and
        generate a warning in <code class="literal">STATEMENT</code> mode. (Bug
        #12092, Bug #30244)
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-fractional-seconds"></a>17.5.1.15 Replication and Fractional Seconds Support</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261267680"></a><a class="indexterm" name="idm46444261266288"></a><p>
        MySQL 8.0 permits fractional seconds for
        <a class="link" href="data-types.html#time" title="11.2.3 The TIME Type"><code class="literal">TIME</code></a>,
        <a class="link" href="data-types.html#datetime" title="11.2.2 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">DATETIME</code></a>, and
        <a class="link" href="data-types.html#datetime" title="11.2.2 The DATE, DATETIME, and TIMESTAMP Types"><code class="literal">TIMESTAMP</code></a> values, with up to
        microseconds (6 digits) precision. See
        <a class="xref" href="data-types.html#fractional-seconds" title="11.2.6 Fractional Seconds in Time Values">Section 11.2.6, “Fractional Seconds in Time Values”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-invoked"></a>17.5.1.16 Replication of Invoked Features</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261259856"></a><a class="indexterm" name="idm46444261258464"></a><a class="indexterm" name="idm46444261257072"></a><a class="indexterm" name="idm46444261255680"></a><a class="indexterm" name="idm46444261254288"></a><a class="indexterm" name="idm46444261252896"></a><a class="indexterm" name="idm46444261251504"></a><p>
        Replication of invoked features such as user-defined functions
        (UDFs) and stored programs (stored procedures and functions,
        triggers, and events) provides the following characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The effects of the feature are always replicated.
          </p></li><li class="listitem"><p>
            The following statements are replicated using
            statement-based replication:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <a class="link" href="sql-statements.html#create-event" title="13.1.13 CREATE EVENT Statement"><code class="literal">CREATE EVENT</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#drop-event" title="13.1.25 DROP EVENT Statement"><code class="literal">DROP EVENT</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#create-procedure" title="13.1.17 CREATE PROCEDURE and CREATE FUNCTION Statements"><code class="literal">CREATE PROCEDURE</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#drop-procedure" title="13.1.29 DROP PROCEDURE and DROP FUNCTION Statements"><code class="literal">DROP PROCEDURE</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#create-function" title="13.1.14 CREATE FUNCTION Statement"><code class="literal">CREATE FUNCTION</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#drop-function" title="13.1.26 DROP FUNCTION Statement"><code class="literal">DROP FUNCTION</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#create-trigger" title="13.1.22 CREATE TRIGGER Statement"><code class="literal">CREATE TRIGGER</code></a>
              </p></li><li class="listitem"><p>
                <a class="link" href="sql-statements.html#drop-trigger" title="13.1.34 DROP TRIGGER Statement"><code class="literal">DROP TRIGGER</code></a>
</p></li></ul>
</div>
<p>
            However, the <span class="emphasis"><em>effects</em></span> of features
            created, modified, or dropped using these statements are
            replicated using row-based replication.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Attempting to replicate invoked features using
              statement-based replication produces the warning
              <span class="errortext">Statement is not safe to log in statement
              format</span>. For example, trying to replicate a UDF
              with statement-based replication generates this warning
              because it currently cannot be determined by the MySQL
              server whether the UDF is deterministic. If you are
              absolutely certain that the invoked feature's effects are
              deterministic, you can safely disregard such warnings.
</p>
</div>
</li><li class="listitem"><p>
            <a class="indexterm" name="idm46444261228000"></a>

            <a class="indexterm" name="idm46444261226608"></a>

            <a class="indexterm" name="idm46444261225216"></a>

            <a class="indexterm" name="idm46444261223824"></a>

            In the case of <a class="link" href="sql-statements.html#create-event" title="13.1.13 CREATE EVENT Statement"><code class="literal">CREATE EVENT</code></a>
            and <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT</code></a>:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                The status of the event is set to
                <code class="literal">SLAVESIDE_DISABLED</code> on the slave
                regardless of the state specified (this does not apply
                to <a class="link" href="sql-statements.html#drop-event" title="13.1.25 DROP EVENT Statement"><code class="literal">DROP EVENT</code></a>).
              </p></li><li class="listitem"><p>
                The master on which the event was created is identified
                on the slave by its server ID. The
                <code class="literal">ORIGINATOR</code> column in
                <a class="link" href="information-schema.html#events-table" title="25.13 The INFORMATION_SCHEMA EVENTS Table"><code class="literal">INFORMATION_SCHEMA.EVENTS</code></a>
                stores this information. See
                <a class="xref" href="information-schema.html#events-table" title="25.13 The INFORMATION_SCHEMA EVENTS Table">Section 25.13, “The INFORMATION_SCHEMA EVENTS Table”</a>, and
                <a class="xref" href="sql-statements.html#show-events" title="13.7.7.18 SHOW EVENTS Statement">Section 13.7.7.18, “SHOW EVENTS Statement”</a>, for more information.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            The feature implementation resides on the slave in a
            renewable state so that if the master fails, the slave can
            be used as the master without loss of event processing.
</p></li></ul>
</div>
<p>
        To determine whether there are any scheduled events on a MySQL
        server that were created on a different server (that was acting
        as a replication master), query the
        <a class="link" href="information-schema.html#events-table" title="25.13 The INFORMATION_SCHEMA EVENTS Table"><code class="literal">INFORMATION_SCHEMA.EVENTS</code></a> table in
        a manner similar to what is shown here:
      </p><pre data-lang="sql" class="programlisting">SELECT EVENT_SCHEMA, EVENT_NAME
    FROM INFORMATION_SCHEMA.EVENTS
    WHERE STATUS = 'SLAVESIDE_DISABLED';</pre><p>
        Alternatively, you can use the <a class="link" href="sql-statements.html#show-events" title="13.7.7.18 SHOW EVENTS Statement"><code class="literal">SHOW
        EVENTS</code></a> statement, like this:
      </p><pre data-lang="sql" class="programlisting">SHOW EVENTS
    WHERE STATUS = 'SLAVESIDE_DISABLED';</pre><p>
        When promoting a replication slave having such events to a
        replication master, you must enable each event using
        <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT
        <em class="replaceable"><code>event_name</code></em> ENABLE</code></a>, where
        <em class="replaceable"><code>event_name</code></em> is the name of the event.
      </p><p>
        If more than one master was involved in creating events on this
        slave, and you wish to identify events that were created only on
        a given master having the server ID
        <em class="replaceable"><code>master_id</code></em>, modify the previous query
        on the <a class="link" href="information-schema.html#events-table" title="25.13 The INFORMATION_SCHEMA EVENTS Table"><code class="literal">EVENTS</code></a> table to include the
        <code class="literal">ORIGINATOR</code> column, as shown here:
      </p><pre data-lang="sql" class="programlisting">SELECT EVENT_SCHEMA, EVENT_NAME, ORIGINATOR
    FROM INFORMATION_SCHEMA.EVENTS
    WHERE STATUS = 'SLAVESIDE_DISABLED'
    AND   ORIGINATOR = '<em class="replaceable"><code>master_id</code></em>'
</pre><p>
        You can employ <code class="literal">ORIGINATOR</code> with the
        <a class="link" href="sql-statements.html#show-events" title="13.7.7.18 SHOW EVENTS Statement"><code class="literal">SHOW EVENTS</code></a> statement in a
        similar fashion:
      </p><pre data-lang="sql" class="programlisting">SHOW EVENTS
    WHERE STATUS = 'SLAVESIDE_DISABLED'
    AND   ORIGINATOR = '<em class="replaceable"><code>master_id</code></em>'
</pre><p>
        Before enabling events that were replicated from the master, you
        should disable the MySQL Event Scheduler on the slave (using a
        statement such as <code class="literal">SET GLOBAL event_scheduler =
        OFF;</code>), run any necessary <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER
        EVENT</code></a> statements, restart the server, then re-enable
        the Event Scheduler on the slave afterward (using a statement
        such as <code class="literal">SET GLOBAL event_scheduler = ON;</code>)-
      </p><p>
        If you later demote the new master back to being a replication
        slave, you must disable manually all events enabled by the
        <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT</code></a> statements. You can
        do this by storing in a separate table the event names from the
        <a class="link" href="sql-statements.html#select" title="13.2.10 SELECT Statement"><code class="literal">SELECT</code></a> statement shown
        previously, or using <a class="link" href="sql-statements.html#alter-event" title="13.1.3 ALTER EVENT Statement"><code class="literal">ALTER EVENT</code></a>
        statements to rename the events with a common prefix such as
        <code class="literal">replicated_</code> to identify them.
      </p><p>
        If you rename the events, then when demoting this server back to
        being a replication slave, you can identify the events by
        querying the <a class="link" href="information-schema.html#events-table" title="25.13 The INFORMATION_SCHEMA EVENTS Table"><code class="literal">EVENTS</code></a> table, as shown
        here:
      </p><pre data-lang="sql" class="programlisting">SELECT CONCAT(EVENT_SCHEMA, '.', EVENT_NAME) AS 'Db.Event'
      FROM INFORMATION_SCHEMA.EVENTS
WHERE INSTR(EVENT_NAME, 'replicated_') = 1;</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-json"></a>17.5.1.17 Replication of JSON Documents</h4>

</div>

</div>

</div>
<p>
        Before MySQL 8.0, an update to a JSON column was always written
        to the binary log as the complete document. In MySQL
        8.0, it is possible to log partial updates to JSON
        documents (see <a class="xref" href="data-types.html#json-partial-updates" title="Partial Updates of JSON Values">Partial Updates of JSON Values</a>), which is
        more efficient. The logging behavior depends on the format used,
        as described here:
      </p><p><b>Statement-based replication. </b>
          JSON partial updates are always logged as partial updates.
          This cannot be disabled when using statement-based logging.
        </p><p><b>Row-based replication. </b>
          JSON partial updates are not logged as such by default, but
          instead are logged as complete documents. To enable logging of
          partial updates, set
          <a class="link" href="replication.html#sysvar_binlog_row_value_options"><code class="literal">binlog_row_value_options=PARTIAL_JSON</code></a>.
          If a replication master has this variable set, partial updates
          received from that master are handled and applied by a
          replication slave regardless of the slave's own setting for
          the variable.
        </p><p>
        Servers running MySQL 8.0.2 or earlier do not recognize the log
        events used for JSON partial updates. For this reason, when
        replicating to such a server from a server running MySQL 8.0.3
        or later, <code class="literal">binlog_row_value_options</code> must be
        disabled on the master by setting this variable to
        <code class="literal">''</code> (empty string). See the description of
        this variable for more information.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-limit"></a>17.5.1.18 Replication and LIMIT</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261178784"></a><a class="indexterm" name="idm46444261177392"></a><p>
        Statement-based replication of <code class="literal">LIMIT</code> clauses
        in <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a>,
        <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>, and
        <a class="link" href="sql-statements.html#insert-select" title="13.2.6.1 INSERT ... SELECT Statement"><code class="literal">INSERT ...
        SELECT</code></a> statements is unsafe since the order of the
        rows affected is not defined. (Such statements can be replicated
        correctly with statement-based replication only if they also
        contain an <code class="literal">ORDER BY</code> clause.) When such a
        statement is encountered:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            When using <code class="literal">STATEMENT</code> mode, a warning that
            the statement is not safe for statement-based replication is
            now issued.
          </p><p>
            When using <code class="literal">STATEMENT</code> mode, warnings are
            issued for DML statements containing
            <code class="literal">LIMIT</code> even when they also have an
            <code class="literal">ORDER BY</code> clause (and so are made
            deterministic). This is a known issue. (Bug #42851)
          </p></li><li class="listitem"><p>
            When using <code class="literal">MIXED</code> mode, the statement is
            now automatically replicated using row-based mode.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-load-data"></a>17.5.1.19 Replication and LOAD DATA</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261164192"></a><a class="indexterm" name="idm46444261162800"></a><p>
        <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> is considered unsafe
        for statement-based logging (see
        <a class="xref" href="replication.html#replication-rbr-safe-unsafe" title="17.2.1.3 Determination of Safe and Unsafe Statements in Binary Logging">Section 17.2.1.3, “Determination of Safe and Unsafe Statements in Binary Logging”</a>). When
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=MIXED</code></a> is set, the
        statement is logged in row-based format. When
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a> is set,
        note that <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> does not
        generate a warning, unlike other unsafe statements.
      </p><p>
        If you do use <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> when
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a> is set,
        a temporary file containing the data is created on the
        replication slave where the changes are applied. The slave then
        uses a <code class="literal">LOAD DATA INFILE</code> statement to apply
        the changes. If binary log encryption is active on the server,
        note that this temporary file is not encrypted. When encryption
        is required, be sure to use row-based or mixed binary logging
        format instead, which do not create the temporary files.
      </p><p>
        If a <code class="literal">PRIVILEGE_CHECKS_USER</code> account has been
        used to help secure the replication channel (see
        <a class="xref" href="replication.html#replication-privilege-checks" title="17.3.3 Replication Privilege Checks">Section 17.3.3, “Replication Privilege Checks”</a>), it is strongly
        recommended that you log <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD
        DATA</code></a> operations using row-based binary logging
        (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>). If
        <code class="literal">REQUIRE_ROW_FORMAT</code> is set for the channel,
        row-based binary logging is required. With this logging format,
        the <a class="link" href="security.html#priv_file"><code class="literal">FILE</code></a> privilege is not needed
        to execute the event, so do not give the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account this privilege.
        If you need to recover from a replication error involving a
        <code class="literal">LOAD DATA INFILE</code> operation logged in
        statement format, and the replicated event is trusted, you could
        grant the <a class="link" href="security.html#priv_file"><code class="literal">FILE</code></a> privilege to the
        <code class="literal">PRIVILEGE_CHECKS_USER</code> account temporarily,
        removing it after the replicated event has been applied.
      </p><p>
        When <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> reads log events for
        <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a> statements logged in
        statement-based format, a generated local file is created in a
        temporary directory. These temporary files are not automatically
        removed by <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> or any other MySQL
        program. If you do use <a class="link" href="sql-statements.html#load-data" title="13.2.7 LOAD DATA Statement"><code class="literal">LOAD DATA</code></a>
        statements with statement-based binary logging, you should
        delete the temporary files yourself after you no longer need the
        statement log. For more information, see
        <a class="xref" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files">Section 4.6.8, “<span class="command"><strong>mysqlbinlog</strong></span> — Utility for Processing Binary Log Files”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-max-allowed-packet"></a>17.5.1.20 Replication and max_allowed_packet</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261137888"></a><a class="indexterm" name="idm46444261136496"></a><p>
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> sets an
        upper limit on the size of any single message between the MySQL
        server and clients, including replication slaves. If you are
        replicating large column values (such as might be found in
        <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> or
        <a class="link" href="data-types.html#blob" title="11.3.4 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> columns) and
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> is too small
        on the master, the master fails with an error, and the slave
        shuts down the I/O thread. If
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> is too small
        on the slave, this also causes the slave to stop the I/O thread.
      </p><p>
        Row-based replication currently sends all columns and column
        values for updated rows from the master to the slave, including
        values of columns that were not actually changed by the update.
        This means that, when you are replicating large column values
        using row-based replication, you must take care to set
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> large enough
        to accommodate the largest row in any table to be replicated,
        even if you are replicating updates only, or you are inserting
        only relatively small values.
      </p><p>
        On a multi-threaded slave (with
        <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers &gt; 0</code></a>),
        ensure that the
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a>
        system variable is set to a value equal to or greater than the
        setting for the
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> system
        variable on the master. The default setting for
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a>,
        128M, is twice the default setting for
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a>, which is
        64M. <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> limits
        the packet size that the master will send, but the addition of
        an event header can produce a binary log event exceeding this
        size. Also, in row-based replication, a single event can be
        significantly larger than the
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> size,
        because the value of
        <a class="link" href="server-administration.html#sysvar_max_allowed_packet"><code class="literal">max_allowed_packet</code></a> only limits
        each column of the table.
      </p><p>
        The replication slave actually accepts packets up to the limit
        set by its
        <a class="link" href="replication.html#sysvar_slave_max_allowed_packet"><code class="literal">slave_max_allowed_packet</code></a>
        setting, which defaults to the maximum setting of 1GB, to
        prevent a replication failure due to a large packet. However,
        the value of
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a>
        controls the memory that is made available on the slave to hold
        incoming packets. The specified memory is shared among all the
        slave worker queues.
      </p><p>
        The value of
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a> is
        a soft limit, and if an unusually large event (consisting of one
        or multiple packets) exceeds this size, the transaction is held
        until all the slave workers have empty queues, and then
        processed. All subsequent transactions are held until the large
        transaction has been completed. So although unusual events
        larger than
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a> can
        be processed, the delay to clear the queues of all the slave
        workers and the wait to queue subsequent transactions can cause
        lag on the replication slave and decreased concurrency of the
        slave workers.
        <a class="link" href="replication.html#sysvar_slave_pending_jobs_size_max"><code class="literal">slave_pending_jobs_size_max</code></a>
        should therefore be set high enough to accommodate most expected
        event sizes.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-memory"></a>17.5.1.21 Replication and MEMORY Tables</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261110432"></a><a class="indexterm" name="idm46444261109040"></a><p>
        When a master server shuts down and restarts, its
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables become empty. To
        replicate this effect to slaves, the first time that the master
        uses a given <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> table after
        startup, it logs an event that notifies slaves that the table
        must be emptied by writing a
        <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> statement for that table
        to the binary log. This generated event is identifiable by a
        comment in the binary log, and if GTIDs are in use on the
        server, it has a GTID assigned.
      </p><p>
        When a slave server shuts down and restarts, its
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables become empty. This
        causes the slave to be out of synchrony with the master and may
        lead to other failures or cause the slave to stop:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Row-format updates and deletes received from the master may
            fail with <code class="literal">Can't find record in
            '<em class="replaceable"><code>memory_table</code></em>'</code>.
          </p></li><li class="listitem"><p>
            Statements such as
            <a class="link" href="sql-statements.html#insert-select" title="13.2.6.1 INSERT ... SELECT Statement"><code class="literal">INSERT INTO
            ... SELECT FROM
            <em class="replaceable"><code>memory_table</code></em></code></a> may insert
            a different set of rows on the master and slave.
</p></li></ul>
</div>
<p>
        The safe way to restart a slave that is replicating
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables is to first drop or
        delete all rows from the <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a>
        tables on the master and wait until those changes have
        replicated to the slave. Then it is safe to restart the slave.
      </p><p>
        An alternative restart method may apply in some cases. When
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>, you can
        prevent the slave from stopping if you set
        <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode=IDEMPOTENT</code></a>
        before you start the slave again. This allows the slave to
        continue to replicate, but its
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables will still be
        different from those on the master. This can be okay if the
        application logic is such that the contents of
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables can be safely lost
        (for example, if the <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables
        are used for caching).
        <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode=IDEMPOTENT</code></a>
        applies globally to all tables, so it may hide other replication
        errors in non-<a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables.
      </p><p>
        (The method just described is not applicable in NDB Cluster,
        where <a class="link" href="replication.html#sysvar_slave_exec_mode"><code class="literal">slave_exec_mode</code></a> is always
        <code class="literal">IDEMPOTENT</code>, and cannot be changed.)
      </p><p>
        The size of <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables is
        limited by the value of the
        <a class="link" href="server-administration.html#sysvar_max_heap_table_size"><code class="literal">max_heap_table_size</code></a> system
        variable, which is not replicated (see
        <a class="xref" href="replication.html#replication-features-variables" title="17.5.1.38 Replication and Variables">Section 17.5.1.38, “Replication and Variables”</a>). A change in
        <code class="literal">max_heap_table_size</code> takes effect for
        <code class="literal">MEMORY</code> tables that are created or updated
        using <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE
        ... ENGINE = MEMORY</code></a> or <a class="link" href="sql-statements.html#truncate-table" title="13.1.37 TRUNCATE TABLE Statement"><code class="literal">TRUNCATE
        TABLE</code></a> following the change, or for all
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables following a server
        restart. If you increase the value of this variable on the
        master without doing so on the slave, it becomes possible for a
        table on the master to grow larger than its counterpart on the
        slave, leading to inserts that succeed on the master but fail on
        the slave with <span class="errortext">Table is full</span> errors. This
        is a known issue (Bug #48666). In such cases, you must set the
        global value of
        <a class="link" href="server-administration.html#sysvar_max_heap_table_size"><code class="literal">max_heap_table_size</code></a> on the
        slave as well as on the master, then restart replication. It is
        also recommended that you restart both the master and slave
        MySQL servers, to insure that the new value takes complete
        (global) effect on each of them.
      </p><p>
        See <a class="xref" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine">Section 16.3, “The MEMORY Storage Engine”</a>, for more
        information about <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> tables.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-mysqldb"></a>17.5.1.22 Replication of the mysql System Schema</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261072736"></a><a class="indexterm" name="idm46444261071344"></a><a class="indexterm" name="idm46444261069952"></a><a class="indexterm" name="idm46444261068560"></a><p>
        Data modification statements made to tables in the
        <code class="literal">mysql</code> schema are replicated according to the
        value of <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a>; if this
        value is <code class="literal">MIXED</code>, these statements are
        replicated using row-based format. However, statements that
        would normally update this information indirectly—such
        <a class="link" href="sql-statements.html#grant" title="13.7.1.6 GRANT Statement"><code class="literal">GRANT</code></a>,
        <a class="link" href="sql-statements.html#revoke" title="13.7.1.8 REVOKE Statement"><code class="literal">REVOKE</code></a>, and statements
        manipulating triggers, stored routines, and views—are
        replicated to slaves using statement-based replication.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-optimizer"></a>17.5.1.23 Replication and the Query Optimizer</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261060720"></a><a class="indexterm" name="idm46444261059328"></a><p>
        It is possible for the data on the master and slave to become
        different if a statement is written in such a way that the data
        modification is nondeterministic; that is, left up the query
        optimizer. (In general, this is not a good practice, even
        outside of replication.) Examples of nondeterministic statements
        include <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a> or
        <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statements that use
        <code class="literal">LIMIT</code> with no <code class="literal">ORDER BY</code>
        clause; see <a class="xref" href="replication.html#replication-features-limit" title="17.5.1.18 Replication and LIMIT">Section 17.5.1.18, “Replication and LIMIT”</a>, for a
        detailed discussion of these.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-partitioning"></a>17.5.1.24 Replication and Partitioning</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261052432"></a><a class="indexterm" name="idm46444261051040"></a><p>
        Replication is supported between partitioned tables as long as
        they use the same partitioning scheme and otherwise have the
        same structure except where an exception is specifically allowed
        (see <a class="xref" href="replication.html#replication-features-differing-tables" title="17.5.1.9 Replication with Differing Table Definitions on Master and Slave">Section 17.5.1.9, “Replication with Differing Table Definitions on Master and Slave”</a>).
      </p><p>
        Replication between tables having different partitioning is
        generally not supported. This because statements (such as
        <a class="link" href="sql-statements.html#alter-table-partition-operations" title="13.1.9.1 ALTER TABLE Partition Operations"><code class="literal">ALTER
        TABLE ... DROP PARTITION</code></a>) acting directly on
        partitions in such cases may produce different results on master
        and slave. In the case where a table is partitioned on the
        master but not on the slave, any statements operating on
        partitions on the master's copy of the slave fail on the
        slave. When the slave's copy of the table is partitioned
        but the master's copy is not, statements acting on
        partitions cannot be run on the master without causing errors
        there.
      </p><p>
        Due to these dangers of causing replication to fail entirely (on
        account of failed statements) and of inconsistencies (when the
        result of a partition-level SQL statement produces different
        results on master and slave), we recommend that insure that the
        partitioning of any tables to be replicated from the master is
        matched by the slave's versions of these tables.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-repair-table"></a>17.5.1.25 Replication and REPAIR TABLE</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261044144"></a><a class="indexterm" name="idm46444261042752"></a><p>
        When used on a corrupted or otherwise damaged table, it is
        possible for the <a class="link" href="sql-statements.html#repair-table" title="13.7.3.5 REPAIR TABLE Statement"><code class="literal">REPAIR TABLE</code></a>
        statement to delete rows that cannot be recovered. However, any
        such modifications of table data performed by this statement are
        not replicated, which can cause master and slave to lose
        synchronization. For this reason, in the event that a table on
        the master becomes damaged and you use
        <a class="link" href="sql-statements.html#repair-table" title="13.7.3.5 REPAIR TABLE Statement"><code class="literal">REPAIR TABLE</code></a> to repair it, you
        should first stop replication (if it is still running) before
        using <a class="link" href="sql-statements.html#repair-table" title="13.7.3.5 REPAIR TABLE Statement"><code class="literal">REPAIR TABLE</code></a>, then
        afterward compare the master's and slave's copies of
        the table and be prepared to correct any discrepancies manually,
        before restarting replication.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-reserved-words"></a>17.5.1.26 Replication and Reserved Words</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261036208"></a><a class="indexterm" name="idm46444261034816"></a><p>
        You can encounter problems when you attempt to replicate from an
        older master to a newer slave and you make use of identifiers on
        the master that are reserved words in the newer MySQL version
        running on the slave. For example, a table column named
        <code class="literal">rank</code> on a MySQL 5.7 master that is
        replicating to a MySQL 8.0 slave could cause a
        problem because <code class="literal">RANK</code> is a reserved word
        beginning in MySQL 8.0.
      </p><p>
        Replication can fail in such cases with Error 1064
        <span class="errortext">You have an error in your SQL syntax...</span>,
        <span class="emphasis"><em>even if a database or table named using the reserved
        word or a table having a column named using the reserved word is
        excluded from replication</em></span>. This is due to the fact
        that each SQL event must be parsed by the slave prior to
        execution, so that the slave knows which database object or
        objects would be affected. Only after the event is parsed can
        the slave apply any filtering rules defined by
        <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>,
        <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a>,
        <a class="link" href="replication.html#option_mysqld_replicate-ignore-db"><code class="option">--replicate-ignore-db</code></a>, and
        <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a>.
      </p><p>
        To work around the problem of database, table, or column names
        on the master which would be regarded as reserved words by the
        slave, do one of the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Use one or more <a class="link" href="sql-statements.html#alter-table" title="13.1.9 ALTER TABLE Statement"><code class="literal">ALTER TABLE</code></a>
            statements on the master to change the names of any database
            objects where these names would be considered reserved words
            on the slave, and change any SQL statements that use the old
            names to use the new names instead.
          </p></li><li class="listitem"><p>
            In any SQL statements using these database object names,
            write the names as quoted identifiers using backtick
            characters (<code class="literal">`</code>).
</p></li></ul>
</div>
<p>
        For listings of reserved words by MySQL version, see
        <a class="ulink" href="http://dev.mysql.com/doc/mysqld-version-reference/en/mysqld-version-reference-optvar.html" target="_top">Reserved
        Words</a>, in the <em class="citetitle">MySQL Server Version
        Reference</em>. For identifier quoting rules, see
        <a class="xref" href="language-structure.html#identifiers" title="9.2 Schema Object Names">Section 9.2, “Schema Object Names”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-shutdowns"></a>17.5.1.27 Replication and Master or Slave Shutdowns</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444261018880"></a><a class="indexterm" name="idm46444261017488"></a><a class="indexterm" name="idm46444261016096"></a><a class="indexterm" name="idm46444261014704"></a><p>
        It is safe to shut down a master server and restart it later.
        When a slave loses its connection to the master, the slave tries
        to reconnect immediately and retries periodically if that fails.
        The default is to retry every 60 seconds. This may be changed
        with the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a>
        statement. A slave also is able to deal with network
        connectivity outages. However, the slave notices the network
        outage only after receiving no data from the master for
        <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a> seconds. If
        your outages are short, you may want to decrease
        <a class="link" href="replication.html#sysvar_slave_net_timeout"><code class="literal">slave_net_timeout</code></a>. See
        <a class="xref" href="replication.html#replication-solutions-unexpected-slave-halt" title="17.4.2 Handling an Unexpected Halt of a Replication Slave">Section 17.4.2, “Handling an Unexpected Halt of a Replication Slave”</a>.
      </p><p>
        An unclean shutdown (for example, a crash) on the master side
        can result in the master binary log having a final position less
        than the most recent position read by the slave, due to the
        master binary log file not being flushed. This can cause the
        slave not to be able to replicate when the master comes back up.
        Setting <a class="link" href="replication.html#sysvar_sync_binlog"><code class="literal">sync_binlog=1</code></a> in the
        master <code class="filename">my.cnf</code> file helps to minimize this
        problem because it causes the master to flush its binary log
        more frequently. For the greatest possible durability and
        consistency in a replication setup using
        <code class="literal">InnoDB</code> with transactions, you should also set
        <a class="link" href="innodb-storage-engine.html#sysvar_innodb_flush_log_at_trx_commit"><code class="literal">innodb_flush_log_at_trx_commit=1</code></a>.
        With this setting, the contents of the <code class="literal">InnoDB</code>
        redo log buffer are written out to the log file at each
        transaction commit and the log file is flushed to disk. Note
        that the durability of transactions is still not guaranteed with
        this setting, because operating systems or disk hardware may
        tell <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> that the flush-to-disk operation
        has taken place, even though it has not.
      </p><p>
        Shutting down a slave cleanly is safe because it keeps track of
        where it left off. However, be careful that the slave does not
        have temporary tables open; see
        <a class="xref" href="replication.html#replication-features-temptables" title="17.5.1.30 Replication and Temporary Tables">Section 17.5.1.30, “Replication and Temporary Tables”</a>. Unclean
        shutdowns might produce problems, especially if the disk cache
        was not flushed to disk before the problem occurred:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For transactions, the slave commits and then updates
            <code class="filename">relay-log.info</code>. If a crash occurs
            between these two operations, relay log processing will have
            proceeded further than the information file indicates and
            the slave will re-execute the events from the last
            transaction in the relay log after it has been restarted.
          </p></li><li class="listitem"><p>
            A similar problem can occur if the slave updates
            <code class="filename">relay-log.info</code> but the server host
            crashes before the write has been flushed to disk. To
            minimize the chance of this occurring, set
            <a class="link" href="replication.html#sysvar_sync_relay_log_info"><code class="literal">sync_relay_log_info=1</code></a> in
            the slave <code class="filename">my.cnf</code> file. Setting
            <a class="link" href="replication.html#sysvar_sync_relay_log_info"><code class="literal">sync_relay_log_info</code></a> to 0
            causes no writes to be forced to disk and the server relies
            on the operating system to flush the file from time to time.
</p></li></ul>
</div>
<p>
        The fault tolerance of your system for these types of problems
        is greatly increased if you have a good uninterruptible power
        supply.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-slaveerrors"></a>17.5.1.28 Slave Errors During Replication</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260993472"></a><a class="indexterm" name="idm46444260992080"></a><a class="indexterm" name="idm46444260990688"></a><a class="indexterm" name="idm46444260989296"></a><p>
        If a statement produces the same error (identical error code) on
        both the master and the slave, the error is logged, but
        replication continues.
      </p><p>
        If a statement produces different errors on the master and the
        slave, the slave SQL thread terminates, and the slave writes a
        message to its error log and waits for the database
        administrator to decide what to do about the error. This
        includes the case that a statement produces an error on the
        master or the slave, but not both. To address the issue, connect
        to the slave manually and determine the cause of the problem.
        <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> is useful for
        this. Then fix the problem and run <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
        SLAVE</code></a>. For example, you might need to create a
        nonexistent table before you can start the slave again.

</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            If a temporary error is recorded in the slave's error log,
            you do not necessarily have to take any action suggested in
            the quoted error message. Temporary errors should be handled
            by the client retrying the transaction. For example, if the
            slave SQL thread records a temporary error relating to a
            deadlock, you do not need to restart the transaction
            manually on the slave, unless the slave SQL thread
            subsequently terminates with a nontemporary error message.
</p>
</div>
<p>
      </p><p>
        If this error code validation behavior is not desirable, some or
        all errors can be masked out (ignored) with the
        <a class="link" href="replication.html#option_mysqld_slave-skip-errors"><code class="option">--slave-skip-errors</code></a> option.
      </p><p>
        For nontransactional storage engines such as
        <code class="literal">MyISAM</code>, it is possible to have a statement
        that only partially updates a table and returns an error code.
        This can happen, for example, on a multiple-row insert that has
        one row violating a key constraint, or if a long update
        statement is killed after updating some of the rows. If that
        happens on the master, the slave expects execution of the
        statement to result in the same error code. If it does not, the
        slave SQL thread stops as described previously.
      </p><p>
        If you are replicating between tables that use different storage
        engines on the master and slave, keep in mind that the same
        statement might produce a different error when run against one
        version of the table, but not the other, or might cause an error
        for one version of the table, but not the other. For example,
        since <code class="literal">MyISAM</code> ignores foreign key constraints,
        an <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> or
        <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a> statement accessing an
        <code class="literal">InnoDB</code> table on the master might cause a
        foreign key violation but the same statement performed on a
        <code class="literal">MyISAM</code> version of the same table on the slave
        would produce no such error, causing replication to stop.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-sql-mode"></a>17.5.1.29 Replication and Server SQL Mode</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260974112"></a><a class="indexterm" name="idm46444260972720"></a><a class="indexterm" name="idm46444260971328"></a><a class="indexterm" name="idm46444260969936"></a><a class="indexterm" name="idm46444260968544"></a><a class="indexterm" name="idm46444260967152"></a><p>
        Using different server SQL mode settings on the master and the
        slave may cause the same <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>
        statements to be handled differently on the master and the
        slave, leading the master and slave to diverge. For best
        results, you should always use the same server SQL mode on the
        master and on the slave. This advice applies whether you are
        using statement-based or row-based replication.
      </p><p>
        If you are replicating partitioned tables, using different SQL
        modes on the master and the slave is likely to cause issues. At
        a minimum, this is likely to cause the distribution of data
        among partitions to be different in the master's and slave's
        copies of a given table. It may also cause inserts into
        partitioned tables that succeed on the master to fail on the
        slave.
      </p><p>
        For more information, see <a class="xref" href="server-administration.html#sql-mode" title="5.1.11 Server SQL Modes">Section 5.1.11, “Server SQL Modes”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-temptables"></a>17.5.1.30 Replication and Temporary Tables</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260961184"></a><a class="indexterm" name="idm46444260959792"></a><a class="indexterm" name="idm46444260958400"></a><p>
        In MySQL 8.0, when
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
        <code class="literal">ROW</code> or <code class="literal">MIXED</code>, statements
        that exclusively use temporary tables are not logged on the
        master, and therefore the temporary tables are not replicated.
        Statements that involve a mix of temporary and nontemporary
        tables are logged on the master only for the operations on
        nontemporary tables, and the operations on temporary tables are
        not logged. This means that there are never any temporary tables
        on the slave to be lost in the event of an unplanned shutdown by
        the slave. For more information about row-based replication and
        temporary tables, see
        <a class="xref" href="replication.html#replication-rbr-usage-temptables" title="Row-based logging of temporary tables">Row-based logging of temporary tables</a>.


      </p><p>
        When <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> is set to
        <code class="literal">STATEMENT</code>, operations on temporary tables are
        logged on the master and replicated on the slave, provided that
        the statements involving temporary tables can be logged safely
        using statement-based format. In this situation, loss of
        replicated temporary tables on the slave can be an issue. In
        statement-based replication mode,
        <a class="link" href="sql-statements.html#create-table" title="13.1.20 CREATE TABLE Statement"><code class="literal">CREATE TEMPORARY
        TABLE</code></a> and
        <a class="link" href="sql-statements.html#drop-table" title="13.1.32 DROP TABLE Statement"><code class="literal">DROP TEMPORARY
        TABLE</code></a> statements cannot be used inside a transaction,
        procedure, function, or trigger when GTIDs are in use on the
        server (that is, when the
        <a class="link" href="replication.html#sysvar_enforce_gtid_consistency"><code class="literal">enforce_gtid_consistency</code></a> system
        variable is set to <code class="literal">ON</code>). They can be used
        outside these contexts when GTIDs are in use, provided that
        <a class="link" href="server-administration.html#sysvar_autocommit"><code class="literal">autocommit=1</code></a> is set.
      </p><p>
        Because of the differences in behavior between row-based or
        mixed replication mode and statement-based replication mode
        regarding temporary tables, you cannot switch the replication
        format at runtime, if the change applies to a context (global or
        session) that contains any open temporary tables. For more
        details, see the description of the
        <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> option.
      </p><p><b>Safe slave shutdown when using temporary tables. </b>
          In statement-based replication mode, temporary tables are
          replicated except in the case where you stop the slave server
          (not just the slave threads) and you have replicated temporary
          tables that are open for use in updates that have not yet been
          executed on the slave. If you stop the slave server, the
          temporary tables needed by those updates are no longer
          available when the slave is restarted. To avoid this problem,
          do not shut down the slave while it has temporary tables open.
          Instead, use the following procedure:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Issue a <code class="literal">STOP SLAVE SQL_THREAD</code> statement.
          </p></li><li class="listitem"><p>
            Use <a class="link" href="sql-statements.html#show-status" title="13.7.7.35 SHOW STATUS Statement"><code class="literal">SHOW STATUS</code></a> to check the
            value of the
            <a class="link" href="server-administration.html#statvar_Slave_open_temp_tables"><code class="literal">Slave_open_temp_tables</code></a>
            variable.
          </p></li><li class="listitem"><p>
            If the value is not 0, restart the slave SQL thread with
            <code class="literal">START SLAVE SQL_THREAD</code> and repeat the
            procedure later.
          </p></li><li class="listitem"><p>
            When the value is 0, issue a <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin
            shutdown</strong></span></a> command to stop the slave.
</p></li></ol>
</div>
<p><b>Temporary tables and replication options. </b>
          By default, with statement-based replication, all temporary
          tables are replicated; this happens whether or not there are
          any matching <a class="link" href="replication.html#option_mysqld_replicate-do-db"><code class="option">--replicate-do-db</code></a>,
          <a class="link" href="replication.html#option_mysqld_replicate-do-table"><code class="option">--replicate-do-table</code></a>, or
          <a class="link" href="replication.html#option_mysqld_replicate-wild-do-table"><code class="option">--replicate-wild-do-table</code></a>
          options in effect. However, the
          <a class="link" href="replication.html#option_mysqld_replicate-ignore-table"><code class="option">--replicate-ignore-table</code></a> and
          <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
          options are honored for temporary tables. The exception is
          that to enable correct removal of temporary tables at the end
          of a session, a replication slave always replicates a
          <code class="literal">DROP TEMPORARY TABLE IF EXISTS</code> statement,
          regardless of any exclusion rules that would normally apply
          for the specified table.
        </p><p>
        A recommended practice when using statement-based replication is
        to designate a prefix for exclusive use in naming temporary
        tables that you do not want replicated, then employ a
        <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table</code></a>
        option to match that prefix. For example, you might give all
        such tables names beginning with <code class="literal">norep</code> (such
        as <code class="literal">norepmytable</code>,
        <code class="literal">norepyourtable</code>, and so on), then use
        <a class="link" href="replication.html#option_mysqld_replicate-wild-ignore-table"><code class="option">--replicate-wild-ignore-table=norep%</code></a>
        to prevent them from being replicated.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-timeout"></a>17.5.1.31 Replication Retries and Timeouts</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260922944"></a><a class="indexterm" name="idm46444260921552"></a><a class="indexterm" name="idm46444260920160"></a><a class="indexterm" name="idm46444260919152"></a><p>
        The global system variable
        <a class="link" href="replication.html#sysvar_slave_transaction_retries"><code class="literal">slave_transaction_retries</code></a> sets
        the maximum number of times for applier threads on a
        single-threaded or multithreaded replication slave to
        automatically retry failed transactions before stopping.
        Transactions are automatically retried when the SQL thread fails
        to execute them because of an <code class="literal">InnoDB</code>
        deadlock, or when the transaction's execution time exceeds the
        <code class="literal">InnoDB</code>
        <a class="link" href="innodb-storage-engine.html#sysvar_innodb_lock_wait_timeout"><code class="literal">innodb_lock_wait_timeout</code></a> value.
        If a transaction has a non-temporary error that will prevent it
        from ever succeeding, it is not retried.
      </p><p>
        The default setting for
        <a class="link" href="replication.html#sysvar_slave_transaction_retries"><code class="literal">slave_transaction_retries</code></a> is
        10, meaning that a failing transaction with an apparently
        temporary error is retried 10 times before the applier thread
        stops. Setting the variable to 0 disables automatic retrying of
        transactions. On a multithreaded slave, the specified number of
        transaction retries can take place on all applier threads of all
        channels. The Performance Schema table
        <a class="link" href="performance-schema.html#replication-applier-status-table" title="26.12.11.4 The replication_applier_status Table"><code class="literal">replication_applier_status</code></a> shows
        the total number of transaction retries that took place on each
        replication channel, in the
        <code class="literal">COUNT_TRANSACTIONS_RETRIES</code> column.
      </p><p>
        The process of retrying transactions can cause lag on a
        replication slave or on a Group Replication group member, which
        can be configured as a single-threaded or multithreaded slave.
        The Performance Schema table
        <a class="link" href="performance-schema.html#replication-applier-status-by-worker-table" title="26.12.11.6 The replication_applier_status_by_worker Table"><code class="literal">replication_applier_status_by_worker</code></a>
        shows detailed information on transaction retries by the applier
        threads on a single-threaded or multithreaded slave. This data
        includes timestamps showing how long it took the applier thread
        to apply the last transaction from start to finish (and when the
        transaction currently in progress was started), and how long
        this was after the commit on the original master and the
        immediate master. The data also shows the number of retries for
        the last transaction and the transaction currently in progress,
        and enables you to identify the transient errors that caused the
        transactions to be retried. You can use this information to see
        whether transaction retries are the cause of replication lag,
        and investigate the root cause of the failures that led to the
        retries.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-timezone"></a>17.5.1.32 Replication and Time Zones</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260907360"></a><a class="indexterm" name="idm46444260905968"></a><p>
        By default, master and slave servers assume that they are in the
        same time zone. If you are replicating between servers in
        different time zones, the time zone must be set on both master
        and slave. Otherwise, statements depending on the local time on
        the master are not replicated properly, such as statements that
        use the <a class="link" href="functions.html#function_now"><code class="literal">NOW()</code></a> or
        <a class="link" href="functions.html#function_from-unixtime"><code class="literal">FROM_UNIXTIME()</code></a> functions.
      </p><p>
        Verify that your combination of settings for the system time
        zone (<a class="link" href="server-administration.html#sysvar_system_time_zone"><code class="literal">system_time_zone</code></a>), server
        current time zone (the global value of
        <a class="link" href="server-administration.html#sysvar_time_zone"><code class="literal">time_zone</code></a>), and per-session
        time zones (the session value of
        <a class="link" href="server-administration.html#sysvar_time_zone"><code class="literal">time_zone</code></a>) on the master and
        slave is producing the correct results. In particular, if the
        <a class="link" href="server-administration.html#sysvar_time_zone"><code class="literal">time_zone</code></a> system variable is
        set to the value <code class="literal">SYSTEM</code>, indicating that the
        server time zone is the same as the system time zone, this can
        cause the master and slave to apply different time zones. For
        example, a master could write the following statement in the
        binary log:
      </p><pre data-lang="sql" class="programlisting">SET @@session.time_zone='SYSTEM';</pre><p>
        If this master and its slave have a different setting for their
        system time zones, this statement can produce unexpected results
        on the slave, even if the slave's global
        <a class="link" href="server-administration.html#sysvar_time_zone"><code class="literal">time_zone</code></a> value has been set to
        match the master's. For an explanation of MySQL Server's time
        zone settings, and how to change them, see
        <a class="xref" href="server-administration.html#time-zone-support" title="5.1.14 MySQL Server Time Zone Support">Section 5.1.14, “MySQL Server Time Zone Support”</a>.
      </p><p>
        See also <a class="xref" href="replication.html#replication-features-functions" title="17.5.1.14 Replication and System Functions">Section 17.5.1.14, “Replication and System Functions”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-transaction-inconsistencies"></a>17.5.1.33 Replication and Transaction Inconsistencies</h4>

</div>

</div>

</div>
<p>
        Inconsistencies in the sequence of transactions that have been
        executed from the relay log can occur depending on your
        replication configuration. This section explains how to avoid
        inconsistencies and solve any problems they cause.
      </p><p>
        The following types of inconsistencies can exist:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <span class="emphasis"><em>Half-applied transactions</em></span>. A
            transaction which updates non-transactional tables has
            applied some but not all of its changes.
          </p></li><li class="listitem"><p>
            <span class="emphasis"><em>Gaps</em></span>. A gap in the externalized
            transaction set appears when, given an ordered sequence of
            transactions, a transaction that is later in the sequence is
            applied before some other transaction that is prior in the
            sequence. Gaps can only appear when using a multithreaded
            slave. To avoid gaps occurring, set
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>.
            Up to and including MySQL 8.0.18, this setting requires that
            binary logging (<a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a>)
            and slave update logging
            (<a class="link" href="replication.html#sysvar_log_slave_updates"><code class="literal">log_slave_updates</code></a>) are
            also enabled, which are the default settings from MySQL 8.0.
            From MySQL 8.0.19, binary logging and slave update logging
            are not required on the slave to set
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>,
            and can be disabled if wanted. In all releases, setting
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            requires that
            <a class="link" href="replication.html#sysvar_slave_parallel_type"><code class="literal">slave_parallel_type</code></a> is set
            to <code class="literal">LOGICAL_CLOCK</code>, which is
            <span class="emphasis"><em>not</em></span> the default setting. Note that in
            some specific situations, as listed in the description for
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order</code></a>,
            setting
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order=1</code></a>
            cannot preserve commit order on the slave, so in these cases
            gaps might still appear in the sequence of transactions that
            have been executed from the slave's relay log.
          </p></li><li class="listitem"><p>
            <span class="emphasis"><em>Master log position lag</em></span>. Even in the
            absence of gaps, it is possible that transactions after
            <code class="literal">Exec_master_log_pos</code> have been applied.
            That is, all transactions up to point <code class="literal">N</code>
            have been applied, and no transactions after
            <code class="literal">N</code> have been applied, but
            <code class="literal">Exec_master_log_pos</code> has a value smaller
            than <code class="literal">N</code>. In this situation,
            <code class="literal">Exec_master_log_pos</code> is a <span class="quote">“<span class="quote">low-water
            mark</span>”</span> of the transactions applied, and lags behind
            the position of the most recently applied transaction. This
            can only happen on multithreaded slaves. Enabling
            <a class="link" href="replication.html#sysvar_slave_preserve_commit_order"><code class="literal">slave_preserve_commit_order</code></a>
            does not prevent master log position lag.
</p></li></ul>
</div>
<p>
        The following scenarios are relevant to the existence of
        half-applied transactions, gaps, and master log position lag:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            While slave threads are running, there may be gaps and
            half-applied transactions.
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> shuts down. Both clean and unclean
            shutdown abort ongoing transactions and may leave gaps and
            half-applied transactions.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#kill" title="13.7.8.4 KILL Statement"><code class="literal">KILL</code></a> of replication threads
            (the SQL thread when using a single-threaded slave, the
            coordinator thread when using a multithreaded slave). This
            aborts ongoing transactions and may leave gaps and
            half-applied transactions.
          </p></li><li class="listitem"><p>
            Error in applier threads. This may leave gaps. If the error
            is in a mixed transaction, that transaction is half-applied.
            When using a multithreaded slave, workers which have not
            received an error complete their queues, so it may take time
            to stop all threads.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> when using a
            multithreaded slave. After issuing <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP
            SLAVE</code></a>, the slave waits for any gaps to be filled
            and then updates <code class="literal">Exec_master_log_pos</code>.
            This ensures it never leaves gaps or master log position
            lag, unless any of the cases above applies, in other words,
            before <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> completes,
            either an error happens, or another thread issues
            <a class="link" href="sql-statements.html#kill" title="13.7.8.4 KILL Statement"><code class="literal">KILL</code></a>, or the server restarts.
            In these cases, <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a>
            returns successfully.
          </p></li><li class="listitem"><p>
            If the last transaction in the relay log is only
            half-received and the multithreaded slave coordinator has
            started to schedule the transaction to a worker, then
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> waits up to 60
            seconds for the transaction to be received. After this
            timeout, the coordinator gives up and aborts the
            transaction. If the transaction is mixed, it may be left
            half-completed.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> when using a
            single-threaded slave. If the ongoing transaction only
            updates transactional tables, it is rolled back and
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> stops immediately.
            If the ongoing transaction is mixed,
            <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP SLAVE</code></a> waits up to 60
            seconds for the transaction to complete. After this timeout,
            it aborts the transaction, so it may be left half-completed.
</p></li></ol>
</div>
<p>
        The global variable
        <a class="link" href="replication.html#sysvar_rpl_stop_slave_timeout"><code class="literal">rpl_stop_slave_timeout</code></a> is
        unrelated to the process of stopping the replication threads. It
        only makes the client that issues <a class="link" href="sql-statements.html#stop-slave" title="13.4.2.7 STOP SLAVE Statement"><code class="literal">STOP
        SLAVE</code></a> return to the client, but the replication
        threads continue to try to stop.
      </p><p>
        If a replication channel has gaps, it has the following
        consequences:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            The slave database is in a state that may never have existed
            on the master.
          </p></li><li class="listitem"><p>
            The field <code class="literal">Exec_master_log_pos</code> in
            <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> is only a
            <span class="quote">“<span class="quote">low-water mark</span>”</span>. In other words, transactions
            appearing before the position are guaranteed to have
            committed, but transactions after the position may have
            committed or not.
          </p></li><li class="listitem"><p>
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> statements
            for that channel fail with an error, unless the applier
            threads are running and the <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE
            MASTER TO</code></a> statement only sets receiver options.
          </p></li><li class="listitem"><p>
            If <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> is started with
            <a class="link" href="replication.html#sysvar_relay_log_recovery"><code class="option">--relay-log-recovery</code></a>, no
            recovery is done for that channel, and a warning is printed.
          </p></li><li class="listitem"><p>
            If <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> is used with
            <a class="link" href="programs.html#option_mysqldump_dump-slave"><code class="option">--dump-slave</code></a>, it does not
            record the existence of gaps; thus it prints
            <a class="link" href="sql-statements.html#change-master-to" title="13.4.2.1 CHANGE MASTER TO Statement"><code class="literal">CHANGE MASTER TO</code></a> with
            <code class="literal">RELAY_LOG_POS</code> set to the <span class="quote">“<span class="quote">low-water
            mark</span>”</span> position in
            <code class="literal">Exec_master_log_pos</code>.
          </p><p>
            After applying the dump on another server, and starting the
            replication threads, transactions appearing after the
            position are replicated again. Note that this is harmless if
            GTIDs are enabled (however, in that case it is not
            recommended to use
            <a class="link" href="programs.html#option_mysqldump_dump-slave"><code class="option">--dump-slave</code></a>).
</p></li></ol>
</div>
<p>
        If a replication channel has master log position lag but no
        gaps, cases 2 to 5 above apply, but case 1 does not.
      </p><p>
        The master log position information is persisted in binary
        format in the internal table
        <code class="literal">mysql.slave_worker_info</code>.
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE
        [SQL_THREAD]</code></a> always consults this information so that
        it applies only the correct transactions. This remains true even
        if <a class="link" href="replication.html#sysvar_slave_parallel_workers"><code class="literal">slave_parallel_workers</code></a> has
        been changed to 0 before <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
        SLAVE</code></a>, and even if <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
        SLAVE</code></a> is used with <code class="literal">UNTIL</code> clauses.
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE UNTIL
        SQL_AFTER_MTS_GAPS</code></a> only applies as many transactions
        as needed in order to fill in the gaps. If
        <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> is used with
        <code class="literal">UNTIL</code> clauses that tell it to stop before it
        has consumed all the gaps, then it leaves remaining gaps.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> removes the relay
          logs and resets the replication position. Thus issuing
          <a class="link" href="sql-statements.html#reset-slave" title="13.4.2.4 RESET SLAVE Statement"><code class="literal">RESET SLAVE</code></a> on a slave with
          gaps means the slave loses any information about the gaps,
          without correcting the gaps.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-transactions"></a>17.5.1.34 Replication and Transactions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260815856"></a><a class="indexterm" name="idm46444260814464"></a><p><b>Mixing transactional and nontransactional statements within the same
          transaction. </b>
          In general, you should avoid transactions that update both
          transactional and nontransactional tables in a replication
          environment. You should also avoid using any statement that
          accesses both transactional (or temporary) and
          nontransactional tables and writes to any of them.
        </p><p>
        The server uses these rules for binary logging:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If the initial statements in a transaction are
            nontransactional, they are written to the binary log
            immediately. The remaining statements in the transaction are
            cached and not written to the binary log until the
            transaction is committed. (If the transaction is rolled
            back, the cached statements are written to the binary log
            only if they make nontransactional changes that cannot be
            rolled back. Otherwise, they are discarded.)
          </p></li><li class="listitem"><p>
            For statement-based logging, logging of nontransactional
            statements is affected by the
            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            system variable. When this variable is
            <code class="literal">OFF</code> (the default), logging is as just
            described. When this variable is <code class="literal">ON</code>,
            logging occurs immediately for nontransactional statements
            occurring anywhere in the transaction (not just initial
            nontransactional statements). Other statements are kept in
            the transaction cache and logged when the transaction
            commits.
            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            has no effect for row-format or mixed-format binary logging.
</p></li></ul>
</div>
<p><a name="replication-features-transactions-trx-nontrx-mixed"></a><b>Transactional, nontransactional, and mixed statements. </b><a class="indexterm" name="idm46444260803136"></a>
          To apply those rules, the server considers a statement
          nontransactional if it changes only nontransactional tables,
          and transactional if it changes only transactional tables. A
          statement that references both nontransactional and
          transactional tables and updates <span class="emphasis"><em>any</em></span> of
          the tables involved is considered a <span class="quote">“<span class="quote">mixed</span>”</span>
          statement. Mixed statements, like transactional statements,
          are cached and logged when the transaction commits.
        </p><p>
        A mixed statement that updates a transactional table is
        considered unsafe if the statement also performs either of the
        following actions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Updates or reads a temporary table
          </p></li><li class="listitem"><p>
            Reads a nontransactional table and the transaction isolation
            level is less than REPEATABLE_READ
</p></li></ul>
</div>
<p>
        A mixed statement following the update of a transactional table
        within a transaction is considered unsafe if it performs either
        of the following actions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Updates any table and reads from any temporary table
          </p></li><li class="listitem"><p>
            Updates a nontransactional table and
            <a class="link" href="replication.html#sysvar_binlog_direct_non_transactional_updates"><code class="literal">binlog_direct_non_transactional_updates</code></a>
            is OFF
</p></li></ul>
</div>
<p>
        For more information, see
        <a class="xref" href="replication.html#replication-rbr-safe-unsafe" title="17.2.1.3 Determination of Safe and Unsafe Statements in Binary Logging">Section 17.2.1.3, “Determination of Safe and Unsafe Statements in Binary Logging”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          A mixed statement is unrelated to mixed binary logging format.
</p>
</div>
<p>
        In situations where transactions mix updates to transactional
        and nontransactional tables, the order of statements in the
        binary log is correct, and all needed statements are written to
        the binary log even in case of a
        <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">ROLLBACK</code></a>.
        However, when a second connection updates the nontransactional
        table before the first connection transaction is complete,
        statements can be logged out of order because the second
        connection update is written immediately after it is performed,
        regardless of the state of the transaction being performed by
        the first connection.
      </p><p><b>Using different storage engines on master and slave. </b>
          It is possible to replicate transactional tables on the master
          using nontransactional tables on the slave. For example, you
          can replicate an <code class="literal">InnoDB</code> master table as a
          <code class="literal">MyISAM</code> slave table. However, if you do
          this, there are problems if the slave is stopped in the middle
          of a <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">BEGIN</code></a>
          ... <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">COMMIT</code></a> block because the
          slave restarts at the beginning of the
          <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">BEGIN</code></a> block.
        </p><p>
        It is also safe to replicate transactions from
        <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a> tables on the master to
        transactional tables—such as tables that use the
        <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> storage engine—on the
        slave. In such cases, an
        <a class="link" href="server-administration.html#sysvar_autocommit"><code class="literal">AUTOCOMMIT=1</code></a>
        statement issued on the master is replicated, thus enforcing
        <code class="literal">AUTOCOMMIT</code> mode on the slave.
      </p><p>
        When the storage engine type of the slave is nontransactional,
        transactions on the master that mix updates of transactional and
        nontransactional tables should be avoided because they can cause
        inconsistency of the data between the master transactional table
        and the slave nontransactional table. That is, such transactions
        can lead to master storage engine-specific behavior with the
        possible effect of replication going out of synchrony. MySQL
        does not issue a warning about this, so extra care should be
        taken when replicating transactional tables from the master to
        nontransactional tables on the slaves.
      </p><p><b>Changing the binary logging format within transactions. </b>
          The <a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format</code></a> and
          <a class="link" href="replication.html#sysvar_binlog_checksum"><code class="literal">binlog_checksum</code></a> system
          variables are read-only as long as a transaction is in
          progress.
        </p><p>
        Every transaction (including
        <a class="link" href="server-administration.html#sysvar_autocommit"><code class="literal">autocommit</code></a> transactions) is
        recorded in the binary log as though it starts with a
        <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">BEGIN</code></a>
        statement, and ends with either a
        <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">COMMIT</code></a> or a
        <a class="link" href="sql-statements.html#commit" title="13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements"><code class="literal">ROLLBACK</code></a>
        statement. This is even true for statements affecting tables
        that use a nontransactional storage engine (such as
        <a class="link" href="storage-engines.html#myisam-storage-engine" title="16.2 The MyISAM Storage Engine"><code class="literal">MyISAM</code></a>).
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          For restrictions that apply specifically to XA transactions,
          see <a class="xref" href="sql-statements.html#xa-restrictions" title="13.3.8.3 Restrictions on XA Transactions">Section 13.3.8.3, “Restrictions on XA Transactions”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-triggers"></a>17.5.1.35 Replication and Triggers</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260767248"></a><a class="indexterm" name="idm46444260765856"></a><p>
        With statement-based replication, triggers executed on the
        master also execute on the slave. With row-based replication,
        triggers executed on the master do not execute on the slave.
        Instead, the row changes on the master resulting from trigger
        execution are replicated and applied on the slave.
      </p><p>
        This behavior is by design. If under row-based replication the
        slave applied the triggers as well as the row changes caused by
        them, the changes would in effect be applied twice on the slave,
        leading to different data on the master and the slave.
      </p><p>
        If you want triggers to execute on both the master and the
        slave—perhaps because you have different triggers on the
        master and slave—you must use statement-based replication.
        However, to enable slave-side triggers, it is not necessary to
        use statement-based replication exclusively. It is sufficient to
        switch to statement-based replication only for those statements
        where you want this effect, and to use row-based replication the
        rest of the time.
      </p><p>
        A statement invoking a trigger (or function) that causes an
        update to an <code class="literal">AUTO_INCREMENT</code> column is not
        replicated correctly using statement-based replication. MySQL
        8.0 marks such statements as unsafe. (Bug #45677)
      </p><p>
        A trigger can have triggers for different combinations of
        trigger event (<a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a>,
        <a class="link" href="sql-statements.html#update" title="13.2.13 UPDATE Statement"><code class="literal">UPDATE</code></a>,
        <a class="link" href="sql-statements.html#delete" title="13.2.2 DELETE Statement"><code class="literal">DELETE</code></a>) and action time
        (<code class="literal">BEFORE</code>, <code class="literal">AFTER</code>), and
        multiple triggers are permitted.
      </p><p>
        For brevity, <span class="quote">“<span class="quote">multiple triggers</span>”</span> here is shorthand
        for <span class="quote">“<span class="quote">multiple triggers that have the same trigger event
        and action time.</span>”</span>
      </p><p>
        <span class="bold"><strong>Upgrades.</strong></span> Multiple triggers are
        not supported in versions earlier than MySQL 5.7. If you upgrade
        servers in a replication topology that use a version earlier
        than MySQL 5.7, upgrade the replication slaves first and then
        upgrade the master. If an upgraded replication master still has
        old slaves using MySQL versions that do not support multiple
        triggers, an error occurs on those slaves if a trigger is
        created on the master for a table that already has a trigger
        with the same trigger event and action time.
      </p><p>
        <span class="bold"><strong>Downgrades.</strong></span> If you downgrade a
        server that supports multiple triggers to an older version that
        does not, the downgrade has these effects:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For each table that has triggers, all trigger definitions
            are in the <code class="filename">.TRG</code> file for the table.
            However, if there are multiple triggers with the same
            trigger event and action time, the server executes only one
            of them when the trigger event occurs. For information about
            <code class="literal">.TRG</code> files, see the Table Trigger Storage
            section of the MySQL Server Doxygen documentation, available
            at <a class="ulink" href="https://dev.mysql.com/doc/index-other.html" target="_top">https://dev.mysql.com/doc/index-other.html</a>.
          </p></li><li class="listitem"><p>
            If triggers for the table are added or dropped subsequent to
            the downgrade, the server rewrites the table's
            <code class="filename">.TRG</code> file. The rewritten file retains
            only one trigger per combination of trigger event and action
            time; the others are lost.
</p></li></ul>
</div>
<p>
        To avoid these problems, modify your triggers before
        downgrading. For each table that has multiple triggers per
        combination of trigger event and action time, convert each such
        set of triggers to a single trigger as follows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            For each trigger, create a stored routine that contains all
            the code in the trigger. Values accessed using
            <code class="literal">NEW</code> and <code class="literal">OLD</code> can be
            passed to the routine using parameters. If the trigger needs
            a single result value from the code, you can put the code in
            a stored function and have the function return the value. If
            the trigger needs multiple result values from the code, you
            can put the code in a stored procedure and return the values
            using <code class="literal">OUT</code> parameters.
          </p></li><li class="listitem"><p>
            Drop all triggers for the table.
          </p></li><li class="listitem"><p>
            Create one new trigger for the table that invokes the stored
            routines just created. The effect for this trigger is thus
            the same as the multiple triggers it replaces.
</p></li></ol>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-truncate"></a>17.5.1.36 Replication and TRUNCATE TABLE</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260739152"></a><a class="indexterm" name="idm46444260737760"></a><p>
        <a class="link" href="sql-statements.html#truncate-table" title="13.1.37 TRUNCATE TABLE Statement"><code class="literal">TRUNCATE TABLE</code></a> is normally
        regarded as a DML statement, and so would be expected to be
        logged and replicated using row-based format when the binary
        logging mode is <code class="literal">ROW</code> or
        <code class="literal">MIXED</code>. However this caused issues when
        logging or replicating, in <code class="literal">STATEMENT</code> or
        <code class="literal">MIXED</code> mode, tables that used transactional
        storage engines such as <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> when
        the transaction isolation level was <code class="literal">READ
        COMMITTED</code> or <code class="literal">READ UNCOMMITTED</code>,
        which precludes statement-based logging.
      </p><p>
        <a class="link" href="sql-statements.html#truncate-table" title="13.1.37 TRUNCATE TABLE Statement"><code class="literal">TRUNCATE TABLE</code></a> is treated for
        purposes of logging and replication as DDL rather than DML so
        that it can be logged and replicated as a statement. However,
        the effects of the statement as applicable to
        <a class="link" href="innodb-storage-engine.html" title="Chapter 15 The InnoDB Storage Engine"><code class="literal">InnoDB</code></a> and other transactional
        tables on replication slaves still follow the rules described in
        <a class="xref" href="sql-statements.html#truncate-table" title="13.1.37 TRUNCATE TABLE Statement">Section 13.1.37, “TRUNCATE TABLE Statement”</a> governing such tables. (Bug
        #36763)
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-user-names"></a>17.5.1.37 Replication and User Name Length</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260725584"></a><a class="indexterm" name="idm46444260724192"></a><p>
        The maximum length of MySQL user names is 32 characters.
        Replication of user names longer than 16 characters to a slave
        earlier than MySQL 5.7 that supports only shorter user names
        will fail. However, this should occur only when replicating from
        a newer master to an older slave, which is not a recommended
        configuration.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-variables"></a>17.5.1.38 Replication and Variables</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260721008"></a><a class="indexterm" name="idm46444260719616"></a><a class="indexterm" name="idm46444260718224"></a><a class="indexterm" name="idm46444260716832"></a><a class="indexterm" name="idm46444260715440"></a><p>
        System variables are not replicated correctly when using
        <code class="literal">STATEMENT</code> mode, except for the following
        variables when they are used with session scope:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_auto_increment_increment"><code class="literal">auto_increment_increment</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="replication.html#sysvar_auto_increment_offset"><code class="literal">auto_increment_offset</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_character_set_database"><code class="literal">character_set_database</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_database"><code class="literal">collation_database</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_server"><code class="literal">collation_server</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_foreign_key_checks"><code class="literal">foreign_key_checks</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_identity"><code class="literal">identity</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_last_insert_id"><code class="literal">last_insert_id</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_pseudo_thread_id"><code class="literal">pseudo_thread_id</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_sql_auto_is_null"><code class="literal">sql_auto_is_null</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_time_zone"><code class="literal">time_zone</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_timestamp"><code class="literal">timestamp</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_unique_checks"><code class="literal">unique_checks</code></a>
</p></li></ul>
</div>
<p>
        When <code class="literal">MIXED</code> mode is used, the variables in the
        preceding list, when used with session scope, cause a switch
        from statement-based to row-based logging. See
        <a class="xref" href="server-administration.html#binary-log-mixed" title="5.4.4.3 Mixed Binary Logging Format">Section 5.4.4.3, “Mixed Binary Logging Format”</a>.
      </p><p>
        <a class="link" href="server-administration.html#sysvar_sql_mode"><code class="literal">sql_mode</code></a> is also replicated
        except for the
        <a class="link" href="server-administration.html#sqlmode_no_dir_in_create"><code class="literal">NO_DIR_IN_CREATE</code></a> mode; the
        slave always preserves its own value for
        <a class="link" href="server-administration.html#sqlmode_no_dir_in_create"><code class="literal">NO_DIR_IN_CREATE</code></a>, regardless
        of changes to it on the master. This is true for all replication
        formats.
      </p><p>
        However, when <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> parses a
        <code class="literal">SET @@sql_mode =
        <em class="replaceable"><code>mode</code></em></code> statement, the full
        <em class="replaceable"><code>mode</code></em> value, including
        <a class="link" href="server-administration.html#sqlmode_no_dir_in_create"><code class="literal">NO_DIR_IN_CREATE</code></a>, is passed to
        the receiving server. For this reason, replication of such a
        statement may not be safe when <code class="literal">STATEMENT</code> mode
        is in use.
      </p><p>
        The <a class="link" href="server-administration.html#sysvar_default_storage_engine"><code class="literal">default_storage_engine</code></a>
        system variable is not replicated, regardless of the logging
        mode; this is intended to facilitate replication between
        different storage engines.
      </p><p>
        The <a class="link" href="server-administration.html#sysvar_read_only"><code class="literal">read_only</code></a> system variable
        is not replicated. In addition, the enabling this variable has
        different effects with regard to temporary tables, table
        locking, and the <a class="link" href="sql-statements.html#set-password" title="13.7.1.10 SET PASSWORD Statement"><code class="literal">SET PASSWORD</code></a>
        statement in different MySQL versions.
      </p><p>
        The <a class="link" href="server-administration.html#sysvar_max_heap_table_size"><code class="literal">max_heap_table_size</code></a> system
        variable is not replicated. Increasing the value of this
        variable on the master without doing so on the slave can lead
        eventually to <span class="errortext">Table is full</span> errors on the
        slave when trying to execute
        <a class="link" href="sql-statements.html#insert" title="13.2.6 INSERT Statement"><code class="literal">INSERT</code></a> statements on a
        <a class="link" href="storage-engines.html#memory-storage-engine" title="16.3 The MEMORY Storage Engine"><code class="literal">MEMORY</code></a> table on the master that is
        thus permitted to grow larger than its counterpart on the slave.
        For more information, see
        <a class="xref" href="replication.html#replication-features-memory" title="17.5.1.21 Replication and MEMORY Tables">Section 17.5.1.21, “Replication and MEMORY Tables”</a>.
      </p><p>
        In statement-based replication, session variables are not
        replicated properly when used in statements that update tables.
        For example, the following sequence of statements will not
        insert the same data on the master and the slave:
      </p><pre data-lang="sql" class="programlisting">SET max_join_size=1000;
INSERT INTO mytable VALUES(@@max_join_size);</pre><p>
        This does not apply to the common sequence:
      </p><pre data-lang="sql" class="programlisting">SET time_zone=...;
INSERT INTO mytable VALUES(CONVERT_TZ(..., ..., @@time_zone));</pre><p>
        Replication of session variables is not a problem when row-based
        replication is being used, in which case, session variables are
        always replicated safely. See
        <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
      </p><p>
        The following session variables are written to the binary log
        and honored by the replication slave when parsing the binary
        log, regardless of the logging format:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_sql_mode"><code class="literal">sql_mode</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_foreign_key_checks"><code class="literal">foreign_key_checks</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_unique_checks"><code class="literal">unique_checks</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_database"><code class="literal">collation_database</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_collation_server"><code class="literal">collation_server</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="server-administration.html#sysvar_sql_auto_is_null"><code class="literal">sql_auto_is_null</code></a>
</p></li></ul>
</div>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Important
</div>
<p>
          Even though session variables relating to character sets and
          collations are written to the binary log, replication between
          different character sets is not supported.
</p>
</div>
<p>
        To help reduce possible confusion, we recommend that you always
        use the same setting for the
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> system
        variable on both master and slave, especially when you are
        running MySQL on platforms with case-sensitive file systems. The
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> setting
        can only be configured when initializing the server.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="replication-features-views"></a>17.5.1.39 Replication and Views</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260638368"></a><a class="indexterm" name="idm46444260636976"></a><p>
        Views are always replicated to slaves. Views are filtered by
        their own name, not by the tables they refer to. This means that
        a view can be replicated to the slave even if the view contains
        a table that would normally be filtered out by
        <code class="option">replication-ignore-table</code> rules. Care should
        therefore be taken to ensure that views do not replicate table
        data that would normally be filtered for security reasons.
      </p><p>
        Replication from a table to a same-named view is supported using
        statement-based logging, but not when using row-based logging.
        Trying to do so when row-based logging is in effect causes an
        error.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-compatibility"></a>17.5.2 Replication Compatibility Between MySQL Versions</h3>

</div>

</div>

</div>
<p>
      MySQL supports replication from one release series to the next
      higher release series. For example, you can replicate from a
      master running MySQL 5.6 to a slave running MySQL 5.7, from a
      master running MySQL 5.7 to a slave running MySQL 8.0, and so on.
      However, you might encounter difficulties when replicating from an
      older master to a newer slave if the master uses statements or
      relies on behavior no longer supported in the version of MySQL
      used on the slave. For example, foreign key names longer than 64
      characters are no longer supported from MySQL 8.0.
    </p><p>
      The use of more than two MySQL Server versions is not supported in
      replication setups involving multiple masters, regardless of the
      number of master or slave MySQL servers. This restriction applies
      not only to release series, but to version numbers within the same
      release series as well. For example, if you are using a chained or
      circular replication setup, you cannot use MySQL
      8.0.1, MySQL 8.0.2, and MySQL
      8.0.4 concurrently, although you could use any two of
      these releases together.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        It is strongly recommended to use the most recent release
        available within a given MySQL release series because
        replication (and other) capabilities are continually being
        improved. It is also recommended to upgrade masters and slaves
        that use early releases of a release series of MySQL to GA
        (production) releases when the latter become available for that
        release series.
</p>
</div>
<p>
      From MySQL 8.0.14, the server version is recorded in the binary
      log for each transaction for the server that originally committed
      the transaction
      (<a class="link" href="replication.html#sysvar_original_server_version"><code class="literal">original_server_version</code></a>), and
      for the server that is the immediate master of the current server
      in the replication topology
      (<a class="link" href="replication.html#sysvar_immediate_server_version"><code class="literal">immediate_server_version</code></a>).
    </p><p>
      Replication from newer masters to older slaves might be possible,
      but is generally not supported. This is due to a number of
      factors:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Binary log format changes. </b>
            The binary log format can change between major releases.
            While we attempt to maintain backward compatibility, this is
            not always possible. A master might also have optional
            features enabled that are not understood by older slaves,
            such as binary log transaction compression, where the
            resulting compressed transaction payloads cannot be read by
            a slave at a release before MySQL 8.0.20.
          </p><p>
          This also has significant implications for upgrading
          replication servers; see
          <a class="xref" href="replication.html#replication-upgrade" title="17.5.3 Upgrading a Replication Setup">Section 17.5.3, “Upgrading a Replication Setup”</a>, for more information.
        </p></li><li class="listitem"><p>
          For more information about row-based replication, see
          <a class="xref" href="replication.html#replication-formats" title="17.2.1 Replication Formats">Section 17.2.1, “Replication Formats”</a>.
        </p></li><li class="listitem"><p><b>SQL incompatibilities. </b>
            You cannot replicate from a newer master to an older slave
            using statement-based replication if the statements to be
            replicated use SQL features available on the master but not
            on the slave.
          </p><p>
          However, if both the master and the slave support row-based
          replication, and there are no data definition statements to be
          replicated that depend on SQL features found on the master but
          not on the slave, you can use row-based replication to
          replicate the effects of data modification statements even if
          the DDL run on the master is not supported on the slave.
</p></li></ul>
</div>
<p>
      For more information on potential replication issues, see
      <a class="xref" href="replication.html#replication-features" title="17.5.1 Replication Features and Issues">Section 17.5.1, “Replication Features and Issues”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-upgrade"></a>17.5.3 Upgrading a Replication Setup</h3>

</div>

</div>

</div>
<p>
      When you upgrade servers that participate in a replication setup,
      the procedure for upgrading depends on the current server versions
      and the version to which you are upgrading. This section provides
      information about how upgrading affects replication. For general
      information about upgrading MySQL, see <a class="xref" href="installing.html#upgrading" title="2.11 Upgrading MySQL">Section 2.11, “Upgrading MySQL”</a>
    </p><p>
      When you upgrade a master to 8.0 from an earlier
      MySQL release series, you should first ensure that all the slaves
      of this master are using the same 8.0.x release. If
      this is not the case, you should first upgrade the slaves. To
      upgrade each slave, shut it down, upgrade it to the appropriate
      8.0.x version, restart it, and restart replication.
      Relay logs created by the slave after the upgrade are in
      8.0 format.
    </p><p>
      Changes affecting operations in strict SQL mode
      (<a class="link" href="server-administration.html#sqlmode_strict_trans_tables"><code class="literal">STRICT_TRANS_TABLES</code></a> or
      <a class="link" href="server-administration.html#sqlmode_strict_all_tables"><code class="literal">STRICT_ALL_TABLES</code></a>) may result in
      replication failure on an upgraded slave. If you use
      statement-based logging
      (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=STATEMENT</code></a>), if a
      slave is upgraded before the master, the nonupgraded master will
      execute statements without error that may fail on the slave and
      replication will stop. To deal with this, stop all new statements
      on the master and wait until the slaves catch up. Then upgrade the
      slaves. Alternatively, if you cannot stop new statements,
      temporarily change to row-based logging on the master
      (<a class="link" href="replication.html#sysvar_binlog_format"><code class="literal">binlog_format=ROW</code></a>) and wait
      until all slaves have processed all binary logs produced up to the
      point of this change. Then upgrade the slaves.
    </p><p>
      The default character set has changed from
      <code class="literal">latin1</code> to <code class="literal">utf8mb4</code> in MySQL
      8.0. In a replicated setting, when upgrading from MySQL 5.7 to
      8.0, it is advisable to change the default character set back to
      the character set used in MySQL 5.7 before upgrading. After the
      upgrade is completed, the default character set can be changed to
      <code class="literal">utf8mb4</code>. Assuming that the previous defaults
      were used, one way to preserve them is to start the server with
      these lines in the <code class="filename">my.cnf</code> file:
    </p><pre data-lang="ini" class="programlisting">[mysqld]
character_set_server=latin1
collation_server=latin1_swedish_ci</pre><p>
      After the slaves have been upgraded, shut down the master, upgrade
      it to the same 8.0.x release as the slaves, and
      restart it. If you had temporarily changed the master to row-based
      logging, change it back to statement-based logging. The
      8.0 master is able to read the old binary logs
      written prior to the upgrade and to send them to the
      8.0 slaves. The slaves recognize the old format and
      handle it properly. Binary logs created by the master subsequent
      to the upgrade are in 8.0 format. These too are
      recognized by the 8.0 slaves.
    </p><p>
      In other words, when upgrading to MySQL 8.0, the
      slaves must be MySQL 8.0 before you can upgrade the
      master to 8.0. Note that downgrading from
      8.0 to older versions does not work so simply: You
      must ensure that any 8.0 binary log or relay log has
      been fully processed, so that you can remove it before proceeding
      with the downgrade.
    </p><p>
      Some upgrades may require that you drop and re-create database
      objects when you move from one MySQL series to the next. For
      example, collation changes might require that table indexes be
      rebuilt. Such operations, if necessary, are detailed at
      <a class="xref" href="installing.html#upgrading-from-previous-series" title="2.11.4 Changes in MySQL 8.0">Section 2.11.4, “Changes in MySQL 8.0”</a>. It is safest to
      perform these operations separately on the slaves and the master,
      and to disable replication of these operations from the master to
      the slave. To achieve this, use the following procedure:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Stop all the slaves and upgrade them. Restart them with the
          <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option so
          that they do not connect to the master. Perform any table
          repair or rebuilding operations needed to re-create database
          objects, such as use of <code class="literal">REPAIR TABLE</code> or
          <code class="literal">ALTER TABLE</code>, or dumping and reloading
          tables or triggers.
        </p></li><li class="listitem"><p>
          Disable the binary log on the master. To do this without
          restarting the master, execute a <code class="literal">SET sql_log_bin =
          OFF</code> statement. Alternatively, stop the master and
          restart it with the
          <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
          option. If you restart the master, you might also want to
          disallow client connections. For example, if all clients
          connect using TCP/IP, enable the
          <a class="link" href="server-administration.html#sysvar_skip_networking"><code class="literal">skip_networking</code></a> system
          variable when you restart the master.
        </p></li><li class="listitem"><p>
          With the binary log disabled, perform any table repair or
          rebuilding operations needed to re-create database objects.
          The binary log must be disabled during this step to prevent
          these operations from being logged and sent to the slaves
          later.
        </p></li><li class="listitem"><p>
          Re-enable the binary log on the master. If you set
          <a class="link" href="replication.html#sysvar_sql_log_bin"><code class="literal">sql_log_bin</code></a> to
          <code class="literal">OFF</code> earlier, execute a <code class="literal">SET
          sql_log_bin = ON</code> statement. If you restarted the
          master to disable the binary log, restart it without
          <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>,
          and without enabling the
          <a class="link" href="server-administration.html#sysvar_skip_networking"><code class="literal">skip_networking</code></a> system
          variable so that clients and slaves can connect.
        </p></li><li class="listitem"><p>
          Restart the slaves, this time without the
          <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> option.
</p></li></ol>
</div>
<p>
      If you are upgrading an existing replication setup from a version
      of MySQL that does not support global transaction identifiers to a
      version that does, you should not enable GTIDs on either the
      master or the slave before making sure that the setup meets all
      the requirements for GTID-based replication. See
      <a class="xref" href="replication.html#replication-gtids-howto" title="17.1.3.4 Setting Up Replication Using GTIDs">Section 17.1.3.4, “Setting Up Replication Using GTIDs”</a>, which contains
      information about converting existing replication setups to use
      GTID-based replication.
    </p><p>
      Prior to MySQL 8.0.16, when the server is running with global
      transaction identifiers (GTIDs) enabled
      (<a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>), do not enable
      binary logging by <a class="link" href="programs.html#mysql-upgrade" title="4.4.5 mysql_upgrade — Check and Upgrade MySQL Tables"><span class="command"><strong>mysql_upgrade</strong></span></a> (the
      <a class="link" href="programs.html#option_mysql_upgrade_write-binlog"><code class="option">--write-binlog</code></a> option). As
      of MySQL 8.0.16, the server performs the entire MySQL upgrade
      procedure, but disables binary logging during the upgrade, so
      there is no issue.
    </p><p>
      It is not recommended to load a dump file when GTIDs are enabled
      on the server (<a class="link" href="replication.html#sysvar_gtid_mode"><code class="literal">gtid_mode=ON</code></a>), if
      your dump file includes system tables.
      <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> issues DML instructions for the
      system tables which use the non-transactional MyISAM storage
      engine, and this combination is not permitted when GTIDs are
      enabled. Also be aware that loading a dump file from a server with
      GTIDs enabled, into another server with GTIDs enabled, causes
      different transaction identifiers to be generated.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-problems"></a>17.5.4 Troubleshooting Replication</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm46444260572688"></a><p>
      If you have followed the instructions but your replication setup
      is not working, the first thing to do is <span class="emphasis"><em>check the error
      log for messages</em></span>. Many users have lost time by not
      doing this soon enough after encountering problems.
    </p><p>
      If you cannot tell from the error log what the problem was, try
      the following techniques:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Verify that the master has binary logging enabled by issuing a
          <a class="link" href="sql-statements.html#show-master-status" title="13.7.7.23 SHOW MASTER STATUS Statement"><code class="literal">SHOW MASTER STATUS</code></a> statement.
          Binary logging is enabled by default. If binary logging is
          enabled, <code class="literal">Position</code> is nonzero. If binary
          logging is not enabled, verify that you are not running the
          master with any settings that disable binary logging, such as
          the
          <a class="link" href="replication.html#option_mysqld_log-bin"><code class="option">--skip-log-bin</code></a>
          option.
        </p></li><li class="listitem"><p>
          Verify that the <a class="link" href="replication.html#sysvar_server_id"><code class="literal">server_id</code></a>
          system variable was set at startup on both the master and
          slave and that the ID value is unique on each server.
        </p></li><li class="listitem"><p>
          Verify that the slave is running. Use
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a> to check
          whether the <code class="literal">Slave_IO_Running</code> and
          <code class="literal">Slave_SQL_Running</code> values are both
          <code class="literal">Yes</code>. If not, verify the options that were
          used when starting the slave server. For example,
          <a class="link" href="replication.html#option_mysqld_skip-slave-start"><code class="option">--skip-slave-start</code></a> prevents the
          slave threads from starting until you issue a
          <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START SLAVE</code></a> statement.
        </p></li><li class="listitem"><p>
          If the slave is running, check whether it established a
          connection to the master. Use <a class="link" href="sql-statements.html#show-processlist" title="13.7.7.29 SHOW PROCESSLIST Statement"><code class="literal">SHOW
          PROCESSLIST</code></a>, find the I/O and SQL threads and check
          their <code class="literal">State</code> column to see what they
          display. See
          <a class="xref" href="replication.html#replication-implementation-details" title="17.2.2 Replication Implementation Details">Section 17.2.2, “Replication Implementation Details”</a>. If the
          I/O thread state says <code class="literal">Connecting to master</code>,
          check the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              Verify the privileges for the user being used for
              replication on the master.
            </p></li><li class="listitem"><p>
              Check that the host name of the master is correct and that
              you are using the correct port to connect to the master.
              The port used for replication is the same as used for
              client network communication (the default is
              <code class="literal">3306</code>). For the host name, ensure that
              the name resolves to the correct IP address.
            </p></li><li class="listitem"><p>
              Check the configuration file to see whether the
              <a class="link" href="server-administration.html#sysvar_skip_networking"><code class="literal">skip_networking</code></a> system
              variable has been enabled on the master or slave to
              disable networking. If so, comment the setting or remove
              it.
            </p></li><li class="listitem"><p>
              If the master has a firewall or IP filtering
              configuration, ensure that the network port being used for
              MySQL is not being filtered.
            </p></li><li class="listitem"><p>
              Check that you can reach the master by using
              <code class="literal">ping</code> or
              <code class="literal">traceroute</code>/<code class="literal">tracert</code>
              to reach the host.
</p></li></ul>
</div>
</li><li class="listitem"><p>
          If the slave was running previously but has stopped, the
          reason usually is that some statement that succeeded on the
          master failed on the slave. This should never happen if you
          have taken a proper snapshot of the master, and never modified
          the data on the slave outside of the slave thread. If the
          slave stops unexpectedly, it is a bug or you have encountered
          one of the known replication limitations described in
          <a class="xref" href="replication.html#replication-features" title="17.5.1 Replication Features and Issues">Section 17.5.1, “Replication Features and Issues”</a>. If it is a bug, see
          <a class="xref" href="replication.html#replication-bugs" title="17.5.5 How to Report Replication Bugs or Problems">Section 17.5.5, “How to Report Replication Bugs or Problems”</a>, for instructions on how to
          report it.
        </p></li><li class="listitem"><p>
          If a statement that succeeded on the master refuses to run on
          the slave, try the following procedure if it is not feasible
          to do a full database resynchronization by deleting the
          slave's databases and copying a new snapshot from the master:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Determine whether the affected table on the slave is
              different from the master table. Try to understand how
              this happened. Then make the slave's table identical to
              the master's and run <a class="link" href="sql-statements.html#start-slave" title="13.4.2.6 START SLAVE Statement"><code class="literal">START
              SLAVE</code></a>.
            </p></li><li class="listitem"><p>
              If the preceding step does not work or does not apply, try
              to understand whether it would be safe to make the update
              manually (if needed) and then ignore the next statement
              from the master.
            </p></li><li class="listitem"><p>
              If you decide that the slave can skip the next statement
              from the master, issue the following statements:
            </p><pre data-lang="sql" class="programlisting">mysql&gt; <strong class="userinput"><code>SET GLOBAL sql_slave_skip_counter = <em class="replaceable"><code>N</code></em>;</code></strong>
mysql&gt; <strong class="userinput"><code>START SLAVE;</code></strong>
</pre><p>
              The value of <em class="replaceable"><code>N</code></em> should be 1 if
              the next statement from the master does not use
              <code class="literal">AUTO_INCREMENT</code> or
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a>.
              Otherwise, the value should be 2. The reason for using a
              value of 2 for statements that use
              <code class="literal">AUTO_INCREMENT</code> or
              <a class="link" href="functions.html#function_last-insert-id"><code class="literal">LAST_INSERT_ID()</code></a> is that
              they take two events in the binary log of the master.
            </p><p>
              See also
              <a class="xref" href="sql-statements.html#set-global-sql-slave-skip-counter" title="13.4.2.5 SET GLOBAL sql_slave_skip_counter Statement">Section 13.4.2.5, “SET GLOBAL sql_slave_skip_counter Statement”</a>.
            </p></li><li class="listitem"><p>
              If you are sure that the slave started out perfectly
              synchronized with the master, and that no one has updated
              the tables involved outside of the slave thread, then
              presumably the discrepancy is the result of a bug. If you
              are running the most recent version of MySQL, please
              report the problem. If you are running an older version,
              try upgrading to the latest production release to
              determine whether the problem persists.
</p></li></ol>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="replication-bugs"></a>17.5.5 How to Report Replication Bugs or Problems</h3>

</div>

</div>

</div>
<p>
      When you have determined that there is no user error involved, and
      replication still either does not work at all or is unstable, it
      is time to send us a bug report. We need to obtain as much
      information as possible from you to be able to track down the bug.
      Please spend some time and effort in preparing a good bug report.
    </p><p>
      If you have a repeatable test case that demonstrates the bug,
      please enter it into our bugs database using the instructions
      given in <a class="xref" href="introduction.html#bug-reports" title="1.7 How to Report Bugs or Problems">Section 1.7, “How to Report Bugs or Problems”</a>. If you have a
      <span class="quote">“<span class="quote">phantom</span>”</span> problem (one that you cannot duplicate at
      will), use the following procedure:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Verify that no user error is involved. For example, if you
          update the slave outside of the slave thread, the data goes
          out of synchrony, and you can have unique key violations on
          updates. In this case, the slave thread stops and waits for
          you to clean up the tables manually to bring them into
          synchrony. <span class="emphasis"><em>This is not a replication problem. It is
          a problem of outside interference causing replication to
          fail.</em></span>
        </p></li><li class="listitem"><p>
          Ensure that the slave is running with binary logging enabled
          (the <a class="link" href="replication.html#sysvar_log_bin"><code class="literal">log_bin</code></a> system
          variable), and with the
          <a class="link" href="replication.html#sysvar_log_slave_updates"><code class="option">--log-slave-updates</code></a> option
          enabled, which causes the slave to log the updates that it
          receives from the master into its own binary logs. These
          settings are the defaults.
        </p></li><li class="listitem"><p>
          Save all evidence before resetting the replication state. If
          we have no information or only sketchy information, it becomes
          difficult or impossible for us to track down the problem. The
          evidence you should collect is:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              All binary log files from the master
            </p></li><li class="listitem"><p>
              All binary log files from the slave
            </p></li><li class="listitem"><p>
              The output of <a class="link" href="sql-statements.html#show-master-status" title="13.7.7.23 SHOW MASTER STATUS Statement"><code class="literal">SHOW MASTER
              STATUS</code></a> from the master at the time you
              discovered the problem
            </p></li><li class="listitem"><p>
              The output of <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE
              STATUS</code></a> from the slave at the time you discovered
              the problem
            </p></li><li class="listitem"><p>
              Error logs from the master and the slave
</p></li></ul>
</div>
</li><li class="listitem"><p>
          Use <a class="link" href="programs.html#mysqlbinlog" title="4.6.8 mysqlbinlog — Utility for Processing Binary Log Files"><span class="command"><strong>mysqlbinlog</strong></span></a> to examine the binary logs.
          The following should be helpful to find the problem statement.
          <em class="replaceable"><code>log_file</code></em> and
          <em class="replaceable"><code>log_pos</code></em> are the
          <code class="literal">Master_Log_File</code> and
          <code class="literal">Read_Master_Log_Pos</code> values from
          <a class="link" href="sql-statements.html#show-slave-status" title="13.7.7.34 SHOW SLAVE STATUS Statement"><code class="literal">SHOW SLAVE STATUS</code></a>.
        </p><pre data-lang="terminal" class="programlisting">shell&gt; <strong class="userinput"><code>mysqlbinlog --start-position=<em class="replaceable"><code>log_pos</code></em> <em class="replaceable"><code>log_file</code></em> | head</code></strong>
</pre></li></ol>
</div>
<p>
      After you have collected the evidence for the problem, try to
      isolate it as a separate test case first. Then enter the problem
      with as much information as possible into our bugs database using
      the instructions at <a class="xref" href="introduction.html#bug-reports" title="1.7 How to Report Bugs or Problems">Section 1.7, “How to Report Bugs or Problems”</a>.
</p>
</div>

</div>

</div>
<div class="copyright-footer">

</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="storage-engines.html">Prev</a></td>
<td width="20%" align="center"><a accesskey="u" href="">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="group-replication.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 16 Alternative Storage Engines</td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top">Chapter 18 Group Replication</td>
</tr>
</table>
</div>
</body>
</html>
